Re: [doc] User Manual Suggestion

["J. Bruce Fields" <bfields@fieldses.org>]

On Fri, Apr 24, 2009 at 02:27:52PM -0400, Jeff King wrote:
> On Fri, Apr 24, 2009 at 01:38:52PM -0400, J. Bruce Fields wrote:
> 
> > On Fri, Apr 24, 2009 at 10:18:15AM -0500, Michael Witten wrote:
> > > I think that we've already got that tutorial-esque style covered (I
> > > haven't read it in a while):
> > > 
> > >     http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html
> > > 
> > > However, the User Manual should make a Mathematician happy.
> > 
> > I'm all for making mathematicians happy.  But, again, help?:
> > 
> > 	- Specific examples?
> > 	- Patches?  Please, patches?
> > 	- Suggested text?
> > 	- Suggested outline?
> > 
> > There's no shortage of high-level ideas.  What there's always a need for
> > more of is people willing to submit patches, respond to review, etc.
> 
> I usually hate to "me too", but I really want to second this notion. We
> have been getting minor documentation fixups trickling in, and I think
> those really help, and maybe they eventually would make the
> documentation perfect. But I have the feeling we would benefit from
> somebody taking ownership and considering the big picture of how the
> documentation fits together, and then really pushing it forward with
> something concrete.

Yup, and dealing seriously with objections, getting concensus for the
resulting solutions, etc--in other words, being a maintainer.  I thought
I'd be able to do that at some point, but just haven't consistently had
the time.

That said, several smaller suggestions have been made which could be
handled now:

	- I don't think I've seen objections to the idea of a
	  git-revision-specifying manpage, whatever you want to call
	  it--so probably that just needs someone to write the patch.
	- There've been complaints about terms being used before they're
	  defined sufficiently well.  I can believe it, but: specific
	  examples would help!

--b.