Hello, On 23 September 2012 11:14, David Kastrup <[email protected]> wrote: > "Sue Daniels" <[email protected]> writes: > >> Graham Percival wrote Sunday, September 23, 2012 7:50 AM >> > >> If documentation is to be done as a separate activity it should be >> done under an issue anyway, to keep the Bug Squad happy. > > The initial batch of documentation is really the task of the original > author. You can't expect a good documentation writer to decipher the > code and take a guess what it does. But with some luck, a good > documentation writer has the skills or experience to decipher what a > good coder mistakes for good documentation, and take a guess at what it > was supposed to mean.
That is exactly what happened with Mike Solomon's original footnote and pure-unpure container documentation - I still couldn't tell you what one is now, but Mike at least created a half formed patch and sent it to me, I tidied it up - a lot of the 'work' is also understanding/remembering the texinfo syntax and CG guidelines - gave it back to Mike to make sure it still made technical sense, he gave me another edit and explained what I hadn't got quite right (lost in translation so to speak) and it went back and forth a bit. Then when it was ok (for me and Mike) I, as a Doc editor, made a patch and then others chipped in. Mike had the good grace to answer the comments even though I submitted the patch (it was his work after all) and I then made the appropriate edits. But I believe unless we now do something that is backward-incompatible with a (yet) undocumented function in the Notation or Learning manuals that we don't hold back the patch for the code, it would be nice to have it all documented as well, but that isn't always the case. The later footnote syntax was a case in point (I think) where we did change the syntax significantly enough that the old documentation would have been incorrect as opposed to incomplete/missing, we couldn't really push that on the users until had had been documented. James _______________________________________________ lilypond-devel mailing list [email protected] https://lists.gnu.org/mailman/listinfo/lilypond-devel
