Re: CG improvements-collector position (was: [frogs] Frog's Lament)

[Graham Percival]

On Wed, Dec 02, 2009 at 11:25:00AM -0500, Chris Snyder wrote:
> Graham Percival wrote:
>> Despite my agreements to both paragraphs above, I agree more with
>> the first than the second.  Namely, I don't see the point of
>> keeping a list of stuff to add to the docs; that's a recipe for
>> not getting anything done.
>
> I think that can depend on a particular person's work habits. I won't  
> dispute that making lists often serves as a substitute for actual work;  
> other times, however list-making can serve as a catalyst. I know that I  
> work much better when I have a list of tasks, divided into  
> manageable-sized portions, that I can tick off as I get work done. Many  
> "life hacking" self-help gurus also suggest such strategies (such as  
> zenhabits.net's "Most Important Tasks" for each day).

Dumping each link into the docs is *also* a manageable-sized
portion.  Depending on how much reading, interpretation, and
rewriting you want to do, it would take anywhere from 1 to 20
minutes to process each email.  If you want to rewrite stuff but
don't have the time, just save the email in a separate folder and
process it later.

> The problem I see here is that there will be many times when the content  
> of the documentation improvement isn't the only issue - rather, there is  
> a question as to what part of the CG is the appropriate place (maybe the  
> appropriate section isn't even written or outlined yet) - or at times  
> the CG isn't the appropriate place at all (perhaps code comments in some  
> cases, etc.).

If anything suitable for the CG hasn't have an obvious spot, then
the CG needs to be reorganized.  There shouldn't be any questions
about stuff relating to anything other than translations or
programming -- if anything is unclear, I'll fix the structure.

That doesn't immediately help you, since you're doing mostly
programming info... but if you can't find an appropriate spot in
CG 8, then just add a new section at the end called "to-be-sorted
programming stuffs" or something like that.

> Therefore, the issues  
> would start piling up in whatever personal tracking method I use (in the  
> absence of a public issue tracker, I'd probably just create a "CG TODO"  
> IMAP folder). Why not make such a list public to give others the  
> opportunity to contribute?

Because that's a recipe for slacking off.


Look, maybe you're extremely special.  But in all my years of
documentation work, and more importantly *managing* documentation
work, I think that an external list will at best be a hinderance,
and at worst would result in little getting done.  If you're
anything like 95% of people who have worked on the lilypond docs,
then the best way is to declare that you are responsible for
adding info from emails into the CG.  Period.

To mitigate that responsibility / time demand, I'm stating that
all you *need* to do is include a link to the email.  And that
link could even be dumped in a TODO area of the docs.


But at the end of the day, I can't afford to care about this
issue, so do whatever you want.

Cheers,
- Graham