A documentation to-do list

A documentation to-do list

[Chris Riddoch]

Hi, everyone.

Having decided to take it on myself to improve Git's documentation, I
asked on #git if people had particular things they felt I should focus
on.  I also was prompted to put up a page on the wiki to make my to-do
list public.

So, I present:  http://git.or.cz/gitwiki/Documentation_To-Do_List

Add your favorite, specific, lack-of-documentation or badly-described
annoyance here!

-- 
epistemological humility

Re: A documentation to-do list

[Junio C Hamano]

"Chris Riddoch" <riddochc@gmail.com> writes:

> Hi, everyone.
>
> Having decided to take it on myself to improve Git's documentation, I
> asked on #git if people had particular things they felt I should focus
> on.  I also was prompted to put up a page on the wiki to make my to-do
> list public.
>
> So, I present:  http://git.or.cz/gitwiki/Documentation_To-Do_List
>
> Add your favorite, specific, lack-of-documentation or badly-described
> annoyance here!

Thanks.

I would not likely to be writing the updates because I am not a
good writer myself, but if there are things that need to be
explained, both behaviour-wise and intent/design-wise, I am
willing to help this effort.

Aside from lacking minor details here and there I think the
largest problem in the current documentation set is the
organization, though.

Re: A documentation to-do list

[Alan Chandler]

On Wednesday 22 November 2006 01:13, Chris Riddoch wrote:
> Hi, everyone.
>
> Having decided to take it on myself to improve Git's documentation, I
> asked on #git if people had particular things they felt I should focus
> on.  I also was prompted to put up a page on the wiki to make my to-do
> list public.
>
> So, I present:  http://git.or.cz/gitwiki/Documentation_To-Do_List
>
> Add your favorite, specific, lack-of-documentation or badly-described
> annoyance here!

Timely, although I will ask the question here rather than there.

I have started to use git-rebase a lot to try and sort out a project that has 
got lots of long chains of commits on parallel branches doing roughly the 
same thing.  But I do not understand what the --merge flag is about.

git-rebase is clearly doing some form of merge for every commit it moves 
without the  --merge flag, so what does it add?

I thought I understood merging, but clearly I don't.

-- 
Alan Chandler

Re: A documentation to-do list

[Johannes Schindelin]

Hi,

On Tue, 21 Nov 2006, Chris Riddoch wrote:

> Having decided to take it on myself to improve Git's documentation, I
> asked on #git if people had particular things they felt I should focus
> on.

I have a request, which is not about _what_ to document, but _how_. People 
often complained about the bad introduction into git, pointing to 
http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart for a "way 
better" tutorial.

It would be really, really easy to just copy that, and describe git 
instead of hg. (There is no mention of a license there, so that may not be 
allowed, but then, it is too short and obvious to be copyrightable, isn't 
it?) You will find that git commands are way shorter!

So, finally my request: we should _organize_ the documentation such that 
your average Joe Programmer is able to get started with git in 1 minute.

If she is interested in more subtle operations, then she should have a 
technical overview such as "Branching and merging with git", maybe a 
little stripped down to leave complicated (but for normal work 
uninteresting) issues out. With a pot of steaming coffee.

Finally, for complicated issues, there is Documentation/technical, the man 
pages, the source, and the git list (in that order).

Hmmm?

Ciao,
Dscho

Re: A documentation to-do list

[Michael K. Edwards]

On 11/22/06, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:
> So, finally my request: we should _organize_ the documentation such that
> your average Joe Programmer is able to get started with git in 1 minute.

I would modify that to a sort of "choose your own adventure" alternative:
    How to use git mindlessly (branchlessly) in 1 minute, by
pretending it's CVS with funny syntax;
vs.
    How git can make you a better programmer in 1 day, by encouraging
you to think about, experiment with, and comment on interactions
between how you and others are evolving a shared code base.

Cheers,

Re: A documentation to-do list

[lamikr]

Johannes Schindelin wrote:
> Hi,
>
> On Tue, 21 Nov 2006, Chris Riddoch wrote:
>
>   
>> Having decided to take it on myself to improve Git's documentation, I
>> asked on #git if people had particular things they felt I should focus
>> on.
>>     
>
> I have a request, which is not about _what_ to document, but _how_. People 
> often complained about the bad introduction into git, pointing to 
> http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart for a "way 
> better" tutorial.
>   
I agree with this. In addition at least I have always missed official
"home page" as even currently the kernel.org points for example just to

       http://www.kernel.org/pub/software/scm/git/
      
Ok, by clicking the "docs" subfolder one gets to man pages. But man
pages does not specify the basic things like, where is the official git
repository
and how to pull the latest official or development versions from there.
In addition man pages are not the fastest way to get started.
Instead small tutorial for example with a following kind of usage
scenario might be quite useful for many. (I do not know even myself to
step 10 :-)

1) One clones architehture specific git repository
    (for example git-clone
git://git.kernel.org/pub/scm/linux/kernel/git/tmlind/linux-omap-2.6.git)
2) This repository has omap specific things in master branch which is
often synced with main kernel
3) Once omap specific things are working agains the release kernel
(let's say 2.6.16), master is tagged with keys like
       "linux-omap-2.6.16-omap1"
4) User creates "MY_DEV" branch and adds own changes to there
5) User tags the branch with "MY_OMAP1_2_6_16" and releases own
2.6.16-omap1 based kernel
6) Master branch in OMAP is synced with the main kernel which is now
somewhere like 2.6.18-rc5
7) User changes to master branch, pulls the master branch to 2.6.18-rc5
level
8) User switches to MY_DEV branch has pulls it it 2.6.18-rc5 level from
master branch. Fix merge errors and commits them there.
9) Stable team releases bug fix version 2.6.16.25 to own git
10) User wants to release MY_OMAP1_2_6_16_25 version and would like to
use git-pull instead of using patch files
       - How to jump back to tagged version in repository?
       - How to pull the stable team changes here?

Other common issues that comes to my mind are but which are not easy to
find out from the current official
man based documentation:

1) where is the repository and gitweb for git itself. (only man pages
are easy to find out currently from net).
2) how to checkout the latest from there (even announcement emails does
not mention this currently!)
3) how to pull the git repository to newer version when Junio announces
new tar-balls
4) how to change to older tagged version (or to some older non tagged
commit version) and build from there
5) how to create own work branch, commit changes to there and
       a) use git-format-patches to create patch files
       b) automatize the patch sending via emails
       c) use push for sending changes back to master repository
6) what is the difference between origin and master. Can user push
changes to origin or should they always be pushed to master or own branch
7) how to create own repository
8) how to set-up gitweb to show your own git repository
9) how to allow others to pull over http connection from your repository
(this was for example easy, but it is hard to find any documentation
from this)
10) how to allow others to pull over git connection from your repository
(requires git-daemon + touch command with magic keyword)