From: Heiko Voigt <hvoigt@hvoigt.net>
Date: Thu, 21 May 2015 13:04:30 GMT
Subject: Re: [PATCH] submodule documentation: Reorder introductory paragraphs
Message-ID: <20150521130429.GB22553@book.hvoigt.net>
In-Reply-To: <1432163517-22785-1-git-send-email-sbeller@google.com>

On Wed, May 20, 2015 at 04:11:57PM -0700, Stefan Beller wrote:
> It's better to start the man page with a description of what submodules
> actually are instead of saying what they are not.
> 
> Reorder the paragraphs such that
> the first short paragraph introduces the submodule concept,
> the second paragraph highlights the usage of the submodule command,
> the third paragraph giving background information,
> and finally the fourth paragraph discusing alternatives such
> as subtrees and remotes, which we don't want to be confused with.
> 
> This ordering deepens the knowledge on submodules with each paragraph.
> First the basic questions like "How/what" will be answered, while the
> underlying concepts will be taught at a later time.
> 
> Making sure it is not confused with subtrees and remotes is not really
> enhancing knowledge of submodules itself, but rather painting the big
> picture of git concepts, so you could also argue to have it as the second
> paragraph. Personally I think this may confuse readers, specially newcomers
> though.
> 
> Signed-off-by: Stefan Beller <sbeller@google.com>

Looks good to me.

Cheers Heiko