Smalltalk › Pharo › Pharo Smalltalk Developers

Reducing the cost of documentation

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

3 messages Options

alistairgrant

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

Torsten Bergmann

Re: Reducing the cost of documentation

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.

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" <[hidden email]>
> An: "Pharo Development List" <[hidden email]>
> 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
>
>

alistairgrant

Re: Reducing the cost of documentation

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" <[hidden email]>
> > An: "Pharo Development List" <[hidden email]>
> > 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
> >
> >
>