Re: Now What?

Jon Loeliger [off-list ref] writes:

Finally, a procedure or style question.  Should this
write-up be in the form of a structured FAQ?  A stand-alone
expository document?

Earlier I suggested bunch of unconnected Documentation/howto
pages, but I'd like to take it back at least partially.  I have
two alternatives; I do not know which one I prefer more...

A table-of-contents (FAQ-list) with task-oriented categorization
would help guide the users facing "Now What?" situation.  It
might start like this:

	It broke after you tried to ...

	* pull from remote
	  breakage #1 --> see this...
	  breakage #2 --> see that...
	  ...

        * checkout a branch
	  breakage #1 --> see this...
	  breakage #2 --> see that...
	  ...

and each breakage and solution would be a separate document.

If we go with this separate FAQ-list approach, I'd love to keep
the result under Documentation/ hierarchy we ship as part of the
source, but I suspect that building-up this kind of thing might
be better suited to Wiki.  I wonder if there is a Wiki whose
document storage format is in asciidoc, and uses git as its
revision control backend.  Then we could let people update Wiki,
and occasionally merge from there.  We also should be able to
push things back to Wiki, essentially treating Wiki as one of
the repositories from the git side.  Hmm...


The other alternative is to add "NOW WHAT" section to each man
page.  The idea is that "if the last command you ran was this
command and if it did not do what you wanted it to do, here are
its common failure modes and how you would recover from them".
So the materials we covered during the failed pull/merge
discussion would go to "NOW WHAT" section of git-pull(1), with
perhaps git-merge(1) saying "See also".

We would want "EXAMPLES" section for all the major commands as
suggested by Linus anyway, and going this way we _may_ be able
to get away without coming up with the higher level problem
categorization; the user would at least know what the last
command he tried to use was already.