Re: Now What?

Jon Loeliger <jdl@freescale.com> writes:

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.