Re: [GLISS] - alternative viewpoint

[Marc Hohl]

Am 23.09.2012 08:50, schrieb Graham Percival:
> On Sat, Sep 22, 2012 at 01:42:46PM +0200, Marc Hohl wrote:
> > Am 21.09.2012 11:00, schrieb David Kastrup:
> > > A user interface change without documentation or regtest is dead code.
> > Regtests are somewhat mandatory:
> >
> > http://lilypond.org/doc/v2.17/Documentation/contributor/write-regression-tests
> >
> > but the documentation work is not a "you'll have to do" but rather a
> > "it would be nice if" rule.
> Yes, that's deliberate.  There's no point holding back programmers
> who are not comfortable writing code.
Yes, that's how I understand it as well.
> > But at least there should be some automatism that raises an
> > issue "xyz-needs documentation" whenever a patch has made it
> > through the revision process but lacks of a proper documentation
> > (*if* the patch concerns a major change, like my bar line stuff).
> There's already some sort of this:
>    git diff -u -r release/2.14.0-1 -r release/2.15.95-1 \
>      input/regression/
> then check if the new features were added to the docs.
>
> It's already listed in the Major release checklist, although we
> skipped over it at Waltrop.
Ah, ok. The word 'automatism' was perhaps not the best
choice – I had something like a developer's rule in mind:
"If you have a strong feeling that this patch does something
overwhelming and the documentaion is not changed accordingly,
thou mightst raise an issue for that." (carved in stone, scanned,
and included in the CG, of course ;-)
> > In my case, I *will* tackle documentation if nobody else wants to,
> > because I know that this feature needs a change in the docs, but
> > the patch itself has undergone quite 60+ comments (part 1 and 2
> > altogether), so when the documentation work would have been
> > included yet, I think we would be at 100+ (or I had already given
> > up ;-).
> I suggest doing the documentation as a separate patch.
Of course.
> > > We might as well remove it before the next stable release.
> No.
>
> > 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.
Well, my idea was:
(a) to avoid that this issue gets lost
(b) not to alienate the documentation writers, of course!
(c) helping them to find the issues where the docs have to be
improved
(d) to include the user community by announcing these issues
on -user, because
(e) if a user finds out that doing such a task is not very difficult,
he might at some point turn into a developer ;-)

Regards,

Marc