Re: [GLISS] - alternative viewpoint

[David Kastrup]

"Sue Daniels" <address@hidden> writes:

> Graham Percival wrote Sunday, September 23, 2012 7:50 AM
>
>> On Sat, Sep 22, 2012 at 01:42:46PM +0200, Marc Hohl wrote:
>>
>>> So I repeat my proposal again: a developer *must* include
>>> regression tests, he *should* do the doc work, but if he feels
>>> not very comfortable at writing some paragraphs for the
>>> docs, he should *have to* raise an issue about that.
>> 
>> I don't think that piling up a bunch of issues will help.  Rather,
>> we should try to not alienate our existing documentation writers,
>> and once that's done, recruit new doc writers.  It wouldn't be
>> hard for somebody to write docs for every new feature between each
>> release.
>
> I'd prefer to see an issue raised for the documentation by the developer
> at the time the new feature is pushed to staging.  Otherwise it is likely
> to be forgotten.  It was only by chance that I happened to find the
> change to \time recently and my first action was to raise an issue to
> document it.

I want to point out that the original issue also included documentation.
I readily admit that the quality and discoverability of it might have
warranted the attention of more capable documentation writers, but it is
not of the "I change this for my own sake and don't care whether it will
or even can be useful to anybody else ever after" quality.

> 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.

-- 
David Kastrup