Hi Torsten, Thanks for your feedback. On Mon, Aug 20, 2018 at 09:29:35AM +0200, Torsten Bergmann wrote:
Hi Alistair,
I don't think the contribution process hold people back from writing documentation since providing a contribution is easy to do now (see [1] and [2]).
And (even when more cumbersome) I like the review process - as it helped several times in the past to discuss contributions or even fixing them or find trivial typos.
I guess the primary problem is lazyness: people dont like to write documentation as it is always additional effort. Remember that often people do not even write a simple comment on a class to inform about the purpose it was created...
I personally doubt that we increase the number and quality of the provided in-image docu with the proposal.
I agree that code reviews are good - my code is much better for all the feedback I get from various members of this community (I'm not going to name names since I'm bound to leave someone out). And I agree that "laziness" plays a significant role - programmers are renowned for not wanting to write documentation / comments. However I think wikis are a good example demonstrating that documentation can be generated under the right conditions. Admitedly there's more required than making it easy to submit a change - having formatted class comments would also encourage people to maintain the documentation. From memory there are plans to support Pillar in class comments, and the work the Feenk are doing will no doubt improve things. So hopefully formatting will not be an issue soon(ish). So I still think that reducing the cost of submitting documentation changes would be worthwhile. But, given the lack of other replies, it looks like I'm in the minority, so I'll keep quiet (for now :-)). Thanks again, Alistair
Bye T.
[1] https://github.com/pharo-project/pharo/blob/development/CONTRIBUTING.md [2] https://github.com/pharo-project/pharo/wiki/Contribute-a-fix-to-Pharo
Gesendet: Montag, 20. August 2018 um 08:37 Uhr Von: "Alistair Grant" <akgrant0710@gmail.com> An: "Pharo Development List" <pharo-dev@lists.pharo.org> Betreff: [Pharo-dev] Reducing the cost of documentation
Hi Everyone,
The topic of documentation recently came up again on the squeak list and it made me wonder about some of the blocks that currently prevent more contributions to in-image documentation.
One of the things holding back the in-image documentation is that the cost of contributing is too high: apart from actually making the change we currently have to (maybe) open an issue, create a branch, commit and open a PR. Someone with commit privileges then has to review the PR enough and decide to merge it. We then need to manually delete the branch some time later.
This is one of the reasons that wikis have been successful, they lower the cost of making changes.
We could extend iceberg to automatically submit PRs for documentation only commits (it could be a separate option, so that the doco only requirement is enforced), and set up github to auto-accept the PR. Modifying in-image documentation would then become a few extra clicks, significantly lowering the cost.
I'm not familiar with Jenkins, or any other CI system, but hunting around google it looks like it may be possible to directly implement this, if not there are services such as https://mergify.io/ which advertise being able to do this by using flags in the CI to determine whether the PR should be merged (disclaimer, I've never looked at mergify.io, just found it while thinking about this).
Thoughts?
Cheers, Alistair