[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