Re: contributor/user split in docs

[John Mandereau]

Le jeudi 01 janvier 2009 à 21:26 -0800, Graham Percival a écrit :
> While I was working on the new website, I realized that the info I
> was adding would work better as a manual rather than a few web
> pages.  Therefore, in Feb (after 2.13 starts), I'll be creating a
> new manual: the Contributor's Guide.

This has already been suggested by several people including Bertalan
(sorry for the names I can't remember right now), but this idea lacked
the spark you just triggered off.


> (I /was/ going to call it the Developer's Guide, but then I
> realized that "DG" has rather a unfortunate meaning amongst
> computer geeks in my generation, and if my friends heard that I
> was working on the "new DG manual" I'd never live it down. :)

"CG" is fine, as not all contributors are developers, if you define a
developer as somebody who writes code, possibly as a secondary task,
e.g. along packaging.


> This will contain the INSTALL docs, doc policy, "working with
> texinfo" stuff, the git guide, info about what all the branches
> are, where to find gub, any potential tips to translators or
> bugfixers, code style, policy for bug reports, checklist for
> normal and major releases, etc.  Generally, I'll be combining all
> the README documents that nobody (including me) looks at and
> putting them all in one place.

Good idea, but if we go for replace READMEs in plain text with a guide
written in Texinfo, we should make sure this guide is always available
in its latest revision and in a compiled form; this would be currently
http://kainhofer.com/~lilypond/


>   I'll also try to write down all
> the `oral tradition' knowledge about lilypond that various people
> have.

It's not possible to achieve this completely unless you do surgery on
these people's brain :-)


> ... actually, on second thought, perhaps I don't need to wait.  I
> don't think that anything in there should be translated; the
> translators need to read enough English to understand the main
> docs so they should be able to handle their instructions, and (for
> better or worse) we do everything else in English.

Of course.


> John, your opinions as both Translation Guy and the person who'd
> be adding the stubs for this to the build system?

I suggest this guide lives in
Documentation/devel/contributors-guide.texi, with .itexi files as
necessary.  In addition to including this in HTML/PDF documentation
building ("make web"), what about adding a toplevel make target
"devel-doc"?


> (starting from next Sep, I should have a linux machine powerful
> enough to build lilypond, so my excuse will be gone.  However,
> until then... ;)

Unless you have no machine that runs a Unix-like system with at least
512 MB RAM and a 1GHz CPU, your excuse will be gone as soon as I've
documented the makefiles structure in the Guide.

Cheers,
John