[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [GLISS] - alternative viewpoint
From: |
David Kastrup |
Subject: |
Re: [GLISS] - alternative viewpoint |
Date: |
Sun, 23 Sep 2012 12:14:42 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.2.50 (gnu/linux) |
"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
- Re: [GLISS] - alternative viewpoint, (continued)
- Re: [GLISS] - alternative viewpoint, David Kastrup, 2012/09/20
- Re: [GLISS] - alternative viewpoint, Marc Hohl, 2012/09/20
- Message not available
- Re: [GLISS] - alternative viewpoint, Thomas Morley, 2012/09/20
- Re: [GLISS] - alternative viewpoint, Marc Hohl, 2012/09/21
- Re: [GLISS] - alternative viewpoint, David Kastrup, 2012/09/21
- Re: [GLISS] - alternative viewpoint, Marc Hohl, 2012/09/22
- Re: [GLISS] - alternative viewpoint, Janek Warchoł, 2012/09/22
- Re: [GLISS] - alternative viewpoint, Graham Percival, 2012/09/23
- Re: [GLISS] - alternative viewpoint, Marc Hohl, 2012/09/23
- Re: [GLISS] - alternative viewpoint, Sue Daniels, 2012/09/24
- Re: [GLISS] - alternative viewpoint,
David Kastrup <=
- Re: [GLISS] - alternative viewpoint, James, 2012/09/23
- Re: [GLISS] - alternative viewpoint, David Kastrup, 2012/09/23
- Re: [GLISS] - alternative viewpoint, Jan Nieuwenhuizen, 2012/09/24
- Re: [GLISS] - alternative viewpoint, James, 2012/09/24
- Re: [GLISS] - alternative viewpoint, David Kastrup, 2012/09/24
- Re: [GLISS] - alternative viewpoint, Janek Warchoł, 2012/09/22
- Re: [GLISS] - alternative viewpoint, Janek Warchoł, 2012/09/17
- Re: [GLISS] - alternative viewpoint, Janek Warchoł, 2012/09/24
- Re: [GLISS] - alternative viewpoint, David Kastrup, 2012/09/15
- Re: [GLISS] - alternative viewpoint, Werner LEMBERG, 2012/09/15