[Top][All Lists]
[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
- Re: improving the CG, (continued)
- Re: improving the CG, Carl Sorensen, 2009/12/27
- Re: improving the CG, John Mandereau, 2009/12/27
- Re: improving the CG, Carl Sorensen, 2009/12/28
- Re: improving the CG, Trevor Daniels, 2009/12/28
- Re: improving the CG, Colin Campbell, 2009/12/28
- Re: improving the CG, Graham Percival, 2009/12/28
- Re: improving the CG, Colin Campbell, 2009/12/28
- Re: improving the CG, Graham Percival, 2009/12/28
Re: improving the CG, Trevor Daniels, 2009/12/27
Re: improving the CG,
Graham Percival <=
- Re: improving the CG, Mark Polesky, 2009/12/28
- Re: improving the CG, Carl Sorensen, 2009/12/28
- Re: improving the CG, Colin Campbell, 2009/12/28
- Re: improving the CG, Graham Percival, 2009/12/28
- Re: improving the CG, John Mandereau, 2009/12/28
- Re: improving the CG, Graham Percival, 2009/12/28
- Re: improving the CG, Colin Campbell, 2009/12/28
- Re: improving the CG, Graham Percival, 2009/12/28
Re: improving the CG, Graham Percival, 2009/12/28
Re: improving the CG, John Mandereau, 2009/12/28