Re: [GLISS] - alternative viewpoint

[James]

Hello,

On 23 September 2012 11:14, David Kastrup <address@hidden> wrote:
> "Sue Daniels" <address@hidden> 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