When and by whom should changes in Rakudo be documented?

[patrickbkr]

Here's what we are currently usually doing: After each release, someone from the docs team sets up an issue with all changes in the release that need to be documented. Then the docs team works trough that list and documents things.

I think this is not ideal:

• The people most knowledgeable of a change (the implementers) are not the ones documenting the change. As a result the documentation is potentially not as good as it could be.
• The benefits of documentation driven development are neglected.
• Puts pressure on the documentation team as they need to keep up with changes the implementers put into Rakudo and / or Raku.
• The documentation changes happen after the release has happened. This means users won't have documentation for the changes in the latest release.
• This also means, that freezing / versioning the documentation together with each release is not feasable. (That's something the docs team is currently thinking about.)

[patrickbkr]

An obvious solution is for implementers to document their changes right away. So idealy implementation, tests and documentation always come together.

A potential drawback is, that not all implementers are necessarily good documenters thus putting pressure on those implementers. But either people can learn becoming better documenters or the documentation team can help out. (Before the release, that is!)

[patrickbkr]

@JJ I'd value your opinion as you are the one faithfully doing the post-release documentation work for a very long time. (Thank you very much for the huge amount of work you put into this!)

[patrickbkr]

@lizmat I'd value your opinion, as you are the most prolific implementer in Rakudo. (Thank you for all the work you put into making Rakudo better!)

[niner]

Another obvious drawback is, that requiring implementors to write documentation reduces resources available for actual development. It's not like we have got those to spare. Point in case: RakuAST - arguably currently the strategically most important initiative - has not seen any development at all in more than a month, simply because I've been busy with my new job.

Not less important is the question whether implementors even want to write documentation. This being a purely volunteer effort and all.

[vrurg]

+1 to the resources point. I'm even having troubles adding spectests lately to some changes if they are about fixes only. It makes me feel guilty, but better this way than no fixes.

Besides, not with my clumsy English it is to mangle with the docs.

But I will always be around to explain details of the changes I've done.

And all this is written by the one who never releases a module without documenting it first. Preferably in full.

[vrurg]

To make it kinda a separate statement: I'm well aware of the documentation lagging behind. Unfortunately, the problem won't be solved until there are enough volunteers to fill the gaps. No constraints would help because, as @niner stated, we all do it on voluntary basis.

[vrurg]

BTW, the problem has another aspect. One better know the structure of the documentation and the future plans for it. Otherwise this would end up with unmanageable, unreadable, and, consequently, useless mess.

This means one has to spent extra time to keep up with the events in this area. Resources, again...