Re: [GLISS] - alternative viewpoint

[Marc Hohl]

Am 21.09.2012 11:00, schrieb David Kastrup:
> Marc Hohl <address@hidden> writes:
>
> > But I don't want to tackle around with the documentation *yet* while
> > it is not sure that my patch gets accepted and the new interface is
> > considered a good idea by most of the developers.  So while in an
> > ideal world every programmer enhances the documentation on the fly, I
> > don't think it would be a good idea to *force* them to do so.
> 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.

I am quite sure that there are people who are better in writing
documentation than in programming and the other way round.
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).

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

> We might as well remove it before the next stable release.
Of course.

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.

It would be interesting to post such issues on the -user list,
because this would give users a possiblility to contribute *and*
to describe the new feature from a user's point of view which
is not a bad thing, after all.

Regards,

Marc

>