Re: CG chapter 2, first draft

[Graham Percival]

(sorry, re-sending to list as well)


On Mon, Jan 11, 2010 at 7:23 AM, Mark Polesky <address@hidden> wrote:
> Hey everyone.  Here's a first draft of my idea for the new
> CG chapter 2.

Don't use $ in front of examples.  It makes it impossible to
cut&paste!  This is an abomination that probably started in printed
manuals (where you'd have to type it in manually anyway), but has *no*
business being on any kind of webpage.

@example
mkdir ~/lilypond-git/; cd ~/lilypond-git/
git init
@end example

Don't bother quoting the output.

> I say "I hope" because I
> worry that some of you might think it's too much?

Yes and no.  I think a fair chunk of it will be wasted effort, but
it's *your* effort to waste.  As long as 2.1 is easy to find (and it
is), and the rest of the chapter is well-organized (and it is), then I
have nothing to complain about.


That said, a few more comments:
- if you're going to go to all this effort, please eliminate the "git
on windows" section -- for each portion of the (unix-aimed) docs, just
dump the relevant windows instructions on the bottom of the page.
As an aside, I've been working on cross-platform python programming
(on windows), so I've worked with the git bash shell.  Other than
extra instructions saying "type this in carefully" or "here's how to
paste to a git bash window" (I don't remember if _that_ was hard, but
cutting&pasting to/from a cygwin window is a nightmare!), I'm not
certain we need anything different for windows users.  Oh, maybe a
note explaining the directory/ vs. directory\

- please refer to ~/lilypond-git/ as the SOURCE directory, not BUILD
directory.  Or maybe "top source directory".  If anybody touches the
build system, then should be doing an out-of-tree build, in which case
~/lilypond-git definitely isn't the builddir.

- editor: please suggest nano instead of emacs.  I love vim, I respect
and fear emacs, but if somebody doesn't know about unix editors, they
should be using pico or nano.

- a normal confused user doesn't need to know about .git/config.  ok,
I know I said that I wouldn't complain, but I am.  :)
What about adding a
   @subsubheading Technical details
right after the cut&paste "git config --global core.editor pico" line?
 And do this throughout the manual -- give the command(s) to cut&paste
with a minimal explanation, then have the side explanations about
.git/config and whatnot after a sign that lets users know they don't
need to know everything in that section.

- there is no web branch.  Well, ok, there is right at the moment, but
it's dead.  It's not pining for the fjords.  Eliminate all mention of
this from the new git chapter.

- making commits: this section could really benefit from the "short
explanation + command, followed by detailed explanation" approach.  In
fact, when I unfocus my eyes and skim over the section (the usual way
I read computer docs), I don't notice any
 git commit -a
at all.


The TOC looks good, other than slight doubts about 2.6 Repository
directory structure, but that's a problem that existed before.  I'm
thinking about adding a chapter just for building, and maybe that
would fit in better in there.  I'll get back to you about this.

Cheers,
- Graham