On Wed, Dec 06, 2006 at 01:02:58PM -0800, Graham Percival wrote:
> 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....)
--b.
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html