Re: [PATCH] cvs-migration document: make the need for "push" more obvious

From: J. Bruce Fields <bfields@fieldses.org>
Date: Dec 6, 2006, 21:45 UTC
Message-ID: <20061206214546.GB25465@fieldses.org>
In-Reply-To: <45773002.5020409@gmail.com>

On Wed, Dec 06, 2006 at 01:02:58PM -0800, Graham Percival wrote:

Show 5 quoted lines

> I'm in the middle of exam period, I have a term papers to write, and I 
> have two weeks of lilypond bug reports and doc typos to process.  I 
> don't care if git can do branches really nicely or walk my dog or cure 
> cancer.  I can look at that stuff later -- right now I just want to fix 
> things and upload them.

Yeah. It's a tricky problem; different people need different things, and to cover everything (and explain it correctly) the documentation needs to be long; but to ensure that impatient people can get to what they need quickly, there needs to be a short, clear path to their particular need.

A few down-to-earth approaches that could help:

	- Clearer section/chapter titles, so we can generate tables of
	  contents where people can quickly find stuff--so, titles that
	  explain what the section will show you how to do with
	  minimized use of jargon that the user doesn't know yet ("how
	  to keep a repository up-to-date" as opposed to "git-fetch and
	  remotes").

	- As in "Everyday Git", think about what different groups of
	  users need.  But where possible, try to order documentation
	  with the stuff needed by the largest group of people first.
	  (For example, right now all the tutorials start with "git
	  init-db" and "git commit", assuming people are starting a
	  project from scratch, when the more typical usage is probably
	  someone joining an existing project, and possibly doing only
	  read-only stuff at first.)

	- Clearer ordering and dependencies, so when people find the "how
	  to resolve merges" section, they can quickly see what else
	  they'd need to read before that.  (And, yeah, I realize 99% of
	  the time they won't actually do that--they'll just dive right
	  in and try a few examples.  But at least they'll know where to
	  turn if that gets them in trouble....)