Ubuntu Documentation Style Guide

[Jeff Schering]

Greetings.

I am creating a documentation style guide for the Ubuntu docteam.

It would have been nice to just say "use the GNOME styleguide," but
although the GNOME style guide is great, it's not Ubuntu. The Ubuntu
documentation team needs its own style guide because Ubuntu is unique.
Ubuntu is Linux + GNU + Debian + (GNOME and KDE) + the Ubuntu
philosophy. No current style guide covers the entire spectrum of
Ubuntu components.

I have created a plan for the style guide and placed it in the
repository in the styleguide folder. The plan itself is called
styleguide-plan.xml. I have also created the wiki page StyleGuidePlan,
which is styleguide-plan.xml in wiki html format. The content is
identical, it's just the format that's different.

I made the StyleGuidePlan in html markup simply because it was very
easy to convert styleguide-plan.xml to html using xsltproc. If anyone
is seriously disappointed that it is not in Moin, then go ahead and
convert it.

In any case, I want any issues concerning the plan to be raised on a
wiki page I have created specially for that: StyleGuideDiscussion. I
would like most (if not all) discussion to take place on that page. It
needs to be in one place where all can see and contribute.

The document plan is open to revision until May 31. The process I want
to follow is this:
1. changes are discussed on StyleGuideDiscussion
2. those participating decide which changes to incorporate 
3. styleguide-plan.xml is updated in the repos
4. a new html is generated and posted back to the StyleGuidePlan wiki page
5. repeat as needed until May 31

Once the plan is set, a similar process will be used for the style
guide itself, the only difference being that I don't anticipate having
the style guide on the wiki; only in the repos, but if someone wants
to periodically copy the style-guide.xml to the wiki, then go for it.
In any case, the style-guide.xml file probably won't appear in the
repos until the end of May, around the same time the plan is
finalized.

Here is the preliminary section layout of the style guide, taken
directly from the Document Plan for the Ubuntu Documentation Style
Guide:

   1. Preface
         1. List of authors
         2. Legal items (copyright, license, history)
   2. Introduction
         1. The Need for an Ubuntu Documentation Style Guide
         2. Style Guide Precedence
   3. Document Structure
   4. Grammar, Punctuation, Spelling, Style, and Word Usage
   5. DocBook Style
   6. Tricky Words
   7. Writing for an International Audience
   8. Terminology
         1. General
         2. GUI Terms
         3. User Actions
   9. Stylesheet 
   10. Reference Materials 
   
According to the plan, the style guide will be released on August 1,
2005. This will give editors approximately two months before Breezy
Badger is released to review the documentation and bring it into
conformance with the style guide.

Jeff

-- 
GPG Key: 1024D/F23C67E8 2005-02-20 Jeff Schering <jeffschering at gmail.com>