Re: [PATCH v3 0/2] Re: user-manual: general improvements

From: Wincent Colaiuta <win@wincent.com>
Date: May 21, 2009, 16:41 UTC
Message-ID: <F1CD811C-E625-4792-8341-7FA2A13E61AE@wincent.com>
In-Reply-To: <94a0d4530905210847o697dd1f9w2f6ffcb8a109f0ca@mail.gmail.com>

El 21/5/2009, a las 17:47, Felipe Contreras escribió:

Show 23 quoted lines

> On Thu, May 21, 2009 at 4:18 PM, Nicolas Sebrecht <nicolas.s.dev@gmx.fr 
> > wrote:
>> The 21/05/09, Felipe Contreras wrote:
>>> On Thu, May 21, 2009 at 7:15 AM, Jeff King <peff@peff.net> wrote:
>>
> Not all branch names are equal; "master" is not the same as
> "mybranch". "master" has a special meaning, therefore it should be in
> monospace, but "mybranch" is simply a branch name, therefore it should
> be emphazied. If the branch name is complicated you might want to
> delimit it with double quotes: "my-fooish-bar-branch", at least the
> first time you mention it.
>
> File names is a similar story; ".gitignore" is not the same as  
> "test.c".
>
>>> Have you actually looked at the end result?
>>
>> Yes, I think it's much better with your patch but "display-types"  
>> should
>> follow the same rules all over the text.
>
> I disagree. There are no absolutes when writing human-readable  
> documents.

It is human-readable, but for the purposes of this discussion it is much more relevant that it is a _technical_ document.

All good technical documentation that I've seen adheres to consistent standards for display types. A "how to read this book" section in which the formatting of the different types appears is extremely widespread, standard practice.

Here's a very brief sampling for you:

http://svnbook.red-bean.com/nightly/en/svn.preface.conventions.html "Conventions used in this book", from the SVN Book

http://www.freebsd.org/doc/en/books/handbook/book-preface.html "Conventions used in this book", from the FreeBSD Handbook

http://oreilly.com/catalog/debian/chapter/book/prf1_02.html "Conventions used in this book", from O'Reilly's "Learning Debian" book

If you're interested, a Google search for "Conventions used in this book" will net you about 58,000 results to persuse.

Not only are people used to understanding texts written using this kind of guideline, but it makes it easier for contributors as well if their a clear-cut conventions for different display types. They obviate the need for you to explain your reasoning about why "master" is somehow different from "mybranch", and why it should be formatted differently etc.

Cheers, Wincent