[MERGE] core_concepts documentation corrections

Ian Clatworthy ian.clatworthy at internode.on.net
Mon Mar 31 04:42:58 BST 2008


Gary Wilson Jr. wrote:
> This patch contains several minor changes to core_concepts docs:
> 
> * Fixed a couple misspellings.
> * Several punctuation, capitalization, and grammar fixes.
> * Made all bulleted lists use a common indention.
> * Corrected a reST link.
> * Removed an extraneous sentence from branches section.

We should drop the punctuation at the end of simple list items I think.
See below.

> I tried looking for some sort of style guidelines for the documentation,
> but didn't find anything.  Are there any defined standards for the
> documentation?  For example, I noticed that bulleted lists had
> inconsistent indention.  On some, the bullet was in the first column of
> the line, and others it was spaced over one or two spaces.

Good point. I don't think we have any. I'd like to propose that we
follow the Python documentation style guidelines, which are based on the
Apple ones. I've updated http://bazaar-vcs.org/ContributingToTheDocs
accordingly.

For bullet lists, this recommends that either full sentences should be
used for each item or that no closing punctuation is used. For example:

 * This is a sentence.
 * And this is another.

Simple list:

 * A sentence
 * Another one

In comparison, most simple lists I've put in the documentation have no
capitialisation and have closing punctuation on the last (and only the
last) item like this:

 * a sentence
 * another one.

My style is just old habit and no more correct that the Python/Apple one
so we should drop it.

Ian C.



More information about the bazaar mailing list