Re: Outdated and broken online versions of user-manual.html

From: Philip Oakley <philipoakley@iee.org>
Date: May 11, 2013, 11:36 UTC
Message-ID: <BE32A698F2774BD5B5235264B13A46C8@PhilipOakley>
In-Reply-To: <loom.20130511T092853-808@post.gmane.org>

From: "Thomas Ackermann" <th.acker@arcor.de>
Sent: Saturday, May 11, 2013 8:48 AM

Show 37 quoted lines

> W. Trevor King <wking <at> tremily.us> writes:
>
>>
>> I'm also surprised that I couldn't find a more obvious link to the
>> manual from git-scm.com (I ended up taking a “See Also” link from
>> gittutorial(7) [3]).  I'm not sure if this is intentional or not,
>> since git-scm.com does prominently link Pro Git, and that overlaps
>> fairly significantly with the manual.
>>
>> Folks with Git installed will generally have man pages, so it's not a
>> big deal, but having current docs somewhere online to link against
>> would be nice.  I'm also curious if I should be linking against a
>> particular location.
>>
>
> IMHO user-manual is a natural step for a Git beginner after reading 
> one
> of the books like "Pro Git" and before he is ready to digest the man 
> pages.
> But up to now there are several problems with user-manual besides the
> problems described by Trevor:
> (1) Very poor html formatting (document type "book" causes
> ugly TOCs per section and there's a "Part I" without a "Part II")
> (2) Partly outdated content
> (3) Sub-optimal structuring (to-do list as part of the document,
> glossary not at the end of the document)
> (4) User-manual.PDF uses an independent tool chain which makes it
> harder to do improvements for user-manual.html and also is the only
> pdf doc we are creating. IMHO we should remove this altogether.
> (5) Large overlapping with the tutorials. IMHO all of the
> tutorials should be blended into user-manual
>
> I am currently working on (1)-(4) and then aiming for (5).
> Comments are welcome ...
>
> ---
> Thomas

I too had noticed that both the User-Manual and git Everyday are not formatted in a manner that allows them to be accessed via 'git help'.

I recently added a '--guides' option to 'git help' (v1.8.2-377-g73903d0) which will show the common guides but was frustrated that I couldn't include either the user-manual or everday in the list.

I'd welcome the provision of a 'man'/'html' formatted version of the two guides. Are you expecting to make then compatible with the man format?

I would be a little cautious of your point 5 if it squoze everything into one overlong document at the expense of losing the shorter documents - one can't eat a whole melon in one bite ;-) That said there is a significant opportunity for rationalisation and clarity improvement, even if it is only a proper realisation of where we deliberately duplicate information for ease of user learning.

I also liked the idea of all the documenation being collated into one Humongous pdf as a reference (there was a patch a while back - don't have a reference right now).

Philip