Re: Why no review on Doc: NR 1.6.2 - Staff Symbol?

[David Kastrup]

James <address@hidden> writes:

> Hello,
>
> On 4 December 2011 07:57, David Kastrup <address@hidden> wrote:
>
>
>     
>     > Overall lesson: it seems that we should have reviews for more
>     doc
>     > items than we did previously, since neither James nor I are
>     > qualified to deal with advanced lilypond concepts.
>     
>     It is somewhat audacious to assume that a whole _feature_ exists
>     for no good reason.  And adding new information can always be
>     improved later.  But throwing away or modifying old information
>     when one does not even understand what it was doing is a good
>     reason to ask.
>     
>     
>
> Just hang on a second.
>
> When one 'throws away' information that 'one' has already used in his
> own music and has already compiled a full doc _without_ issue of
> example then one 'assumes' that the modification is fine.

The code does not even work at the top of a document.  And proof by
example is good for a lot of things.

> One was not 'not understanding' here,  one (more than 'one' actually)
> was thinking that the change made no difference at all and was purely
> one of style.

Style is rarely without reason.

> So while I am always happy (grateful even) to be corrected and have
> the reason explained, I am slightly 'not happy' about the implication
> of your last paragraph that this was done 'without understanding'.

My understanding of language does not make "thinking that the change
made no difference at all" a subset of "understanding" in this context.

> Seems to me, as it does yourself David, that documentation elsewhere
> (for contexts) could be improved,

No question about that.

> and there was even a request to change something about instrument
> names in this thread from Xavier - because people are 'always' making
> a similar mistake - and yet I see no one stepping forward to help
> improve the documentation until something like this happens and people
> get 'up in arms'.

Cf <URL:http://code.google.com/p/lilypond/issues/detail?id=1995>.  It is
not like I don't try improving the documentation (and it is not like I
actually _do_ a lot in that area either).  But it is not rare when I set
out to document something that at some point of time I decide "I won't
be documenting this incoherent heap of crap.  First I am cleaning up
this mess, and then document the results."

I _am_ already working more or less fulltime on Lilypond without pay,
and you complain that this isn't enough.

> As has always been stated, no is asking for documentation tracker
> entries to be 'verbatim and polished or even complete' when they are
> created, but it sure would help if 'something' was added - even if it
> is just a link to a section or a para about what is bad/good/needs
> improving. It's not like I am (now) busy doing anything else for the
> LP project.

Well, if the code whizs are too lazy documenting what they know and
choose to frolic on the beach instead, they might at least be useful for
proofreading between two sips of Bacardi, don't you think?

-- 
David Kastrup