[MERGE] Revised mini-tutorial

Martin Pool mbp at canonical.com
Tue Oct 2 12:38:45 BST 2007


It looks like James, John and Aaron already covered much of the content
of the patch, so I'll just add that it might also be useful to add some
documentation style guides to the developer guide.  There is no section
about this in HACKING yet, but there could be.

One point from this thread is heading capitalization.  At present even
within HACKING it's inconsistent; being consistent looks better.  I
personally slightly prefer sentence case (ie initial capital plus proper nouns),
which Matthew used in this patch, as more modern and informal and suited
to online documentation.  (Capitals Look a bit like Mock German.)
On the other hand Apple, GNOME and Microsoft agree on using sentence
case, and most of our existing documents use that.

Verbal style is harder to describe.  Somewhere between too formal and
too cute.  It's fine to directly address the reader 'you', but not too
often.

-- 
Martin



More information about the bazaar mailing list