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.

On Thursday 03 November 2005 21:55, Junio C Hamano wrote:

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.

I wonder if Git is the best SCM for a Wiki, as you want per-file
revisions in a Wiki: when reverting a page to a previous version,
this should not modify other pages.
So you have an index and a HEAD for every file.
To snapshot a state of such a multihead repository, it would be
nice to have tag objects able to hold multiple SHAs of commits.
Or can we use tree objects for this?

Josef

Josef Weidendorfer [off-list ref] writes:

On Thursday 03 November 2005 21:55, Junio C Hamano wrote:

quoted

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.

I wonder if Git is the best SCM for a Wiki, as you want per-file
revisions in a Wiki: when reverting a page to a previous version,
this should not modify other pages.

Sorry, I do not see why per-file revisioning is mandatory.
Wouldn't revert or edit of a single page be just a new commit of
the new whole tree with just a single path changed?

I understand that whole tree history may not be much useful in
Wiki environment, but I do not see why it would hurt to have a
whole tree history (except perhaps the commit log may not be
very useful).

In fact, wouldn't svnwiki already does the same thing?

On Thursday 03 November 2005 23:51, Junio C Hamano wrote:

quoted

I wonder if Git is the best SCM for a Wiki, as you want per-file
revisions in a Wiki: when reverting a page to a previous version,
this should not modify other pages.

Sorry, I do not see why per-file revisioning is mandatory.
Wouldn't revert or edit of a single page be just a new commit of
the new whole tree with just a single path changed?

You are right.
Obviously I should get some sleep ;-)

As you said, by adding a new commit for every page revert, you get
a really messy history. If there is vandalism in a Wiki, wouldn't
it be better to be able to get rid of spam versions of one Wiki page?

In fact, wouldn't svnwiki already does the same thing?

Probably. I don't know it.

Josef