lilypond-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: improving the CG


From: Graham Percival
Subject: Re: improving the CG
Date: Sun, 27 Dec 2009 18:15:57 +0000
User-agent: Mutt/1.5.18 (2008-05-17)

On Sat, Dec 26, 2009 at 06:14:22PM -0800, Mark Polesky wrote:
> I imagine that this would lead to an annoying web of
> cross-references, since someone new to Git who starts
> reading the chapter `Using Git' would need to go to the
> appendix for `Starting with Git', then back to the chapter
> for `Downloading branches', then back to the appendix for
> `Basic procedures', etc.

I agree; I think it should be kept in the same chapter.

>  1. Introduction to contributing
>     1.1 Overview of tasks                          (`Help us')
>     1.2 For beginners  [ better title? ]
>     1.3 For developers [ better title? ]

Put 1.3 first, and call it "for experienced unix developers".  The
next one can be "for everybody else".  Or something like that.
There are plenty of windows developers who have never heard of git
or imagined documentation being "compiled" (`doesn't everybody use
word?'), so a split between beginners and developers isn't
sufficient.

>  2. Working with source code
>     2.1 Using the `lilycontrib' GUI
>     2.2 Using Git
>            ** put ref to Git appendix here? **
>         2.2.1 Starting with Git
>               * Installing Git
>               * Initializing a repository
>               * Configuring Git
>         2.2.2 Downloading branches
>               * LilyPond repository sources          (1.1.6)
>               * The `master' branch                  (1.1.3)
>               * The `lilypond/translation' branch    (1.1.4)
>               * Other branches                       (1.1.5)
>         2.2.3 Git on Windows

What about making 2.2 Getting source, then 2.3 basic procedures,
etc ?  That way, all the git stuff is still in the same chapter,
but no section/subsection is unreasonably long.

>  3. Compiling
>     3.4 Post-compilation options
>         3.4.2 Generating documentation             (2.1.4)
>                  (add @ref to building docs w/o compiling)
>               * Building documentation

I'm not entirely comfortable with documentation being
"post-compile".  How about having a "compiling" section (err,
renamed to avoid a clash with the chapter name), with one
subsection for "compiling the binary" and another for "compiling
the documentation" ?

>  4. Documentation work                             (3)
>     * `Building documentation without compiling' here?

I really don't like this.  It belongs in the "compiling" chapter.


Overall, I still think you're trying to do too many things at
once; planning the git chapter(s) and compiling chapters at the
same time is unnecessarily complicated.

Cheers,
- Graham




reply via email to

[Prev in Thread] Current Thread [Next in Thread]