Re: [PATCH] Documentation: enhanced "git for CVS users" doc about shared repositories

From: Steffen Prohaska <prohaska@zib.de>
Date: Nov 7, 2007, 08:07 UTC
Message-ID: <277490E5-2B9A-4BA7-9DD7-C1CEE698B348@zib.de>
In-Reply-To: <47310ACF.4030103@gmail.com>

On Nov 7, 2007, at 1:46 AM, Francesco Pretto wrote:

Show 5 quoted lines

> Junio C Hamano ha scritto:
>>
>> Honestly speaking, I am not too thrilled about making the
>> cvs-migration document much longer than what it currently is.
>>

Maybe the description of setting up a shared repository should go to the user-manual and cvs-migration should refer to the user-manual, instead of the other way round. I don't like the idea that the user-manual is referring to a CVS specific guide. The user manual should be as self-contained as possible.

Show 30 quoted lines

> Honestly speaking, you've spent too much time in looking for every  
> possible
> objections against these simple additions. At least it should be  
> less than the
> time I've spent in measuring every single word of this patch,  
> hoping you could
> consider them for inclusion. You gave me lot of attentions (I am  
> grateful of this,
> really) so I should probably be surprised of the cleanliness of git  
> code, of the
> rigor of the code style, of the clarity of the documentation. But  
> unfortunately,
> I am not. I simply tried to make this document more useful and  
> helpful for a
> wider audience of people that could ever consider of using git in  
> their life.
> And yes, I decided to so because I had trouble myself during  
> initial configurations.
> What's the problem if a document called "git for CVS users" is more  
> explicated?
> What's the problem if it contains as many as possible informations  
> to set up
> git in a viable way and, hopefully, to learn something on how it  
> does work?
>
> I'm sad. Not only because you refused a documentation patch, but  
> because i could
> have sent a "Bug: Documentation Sucks!" to the ml and i would have  
> obtained the
> same thing: nothing.

Don't be unfair. Junio made clear that the documentation should not be cluttered with an introduction to Unix commands. But at least two points (git-shell, git-init.txt) would be accepted if you sent an cleaned-up patch.

I have no good idea how to reconcile your idea of giving more guidance to Unix commands with the idea of having a concise document that assumes a reader with decent Unix knowledge

Maybe you could just add some references to the distribution specific information, or just refer to the man pages.

Maybe you could move the introductory comments to a FAQ-like appendix. It could give brief hints on "How to set up a user account?", "How to setup a world-writable directory?" I'm a bit reluctant to this because we'd need to maintain such information. But I suspect that some users would find them helpful.

One last comment: discussing patches is how the world works on the git mailing list. It happend to me, too, that patches were rejected after a brief or after a lengthy discussion. So, yes, finally sometimes there is no change. But often the discussions reveal a better way of achieving the original goal. Nonetheless, it can be frustrating to the original author.

Thanks for you effort of improving the documentation.

	Steffen