The style guide has been released at version 1.0. It is being changed and updated, and will be released at version 2.0 in April, 2006.
Document Plan for the Style Guide
Audience: The audience for the style guide is the Ubuntu Documentation Team. Although the team's members come from a variety of cultures and backgrounds, they have something in common; the desire to produce high quality documentation. Members of the team are competent writers in the English language, although English is not the first language for many of them.
Document Outline: See the Document Outline section below.
Target Presentation Formats: html, pdf
License: Public Domain
Technologies and Techniques: The style guide is in DocBook xml, and stored in the docteam's Subversion repository.
Release Target: Version 2.0 of the guide will be release in April, 2006.
Links to Current Version: The current version is available from the DocteamProjects page. It is also available in the docteam's Subversion repository. (See below for instructions on how to retrieve it)
How to Contribute: There are two ways to participate: 1) send an email to the ubuntu-doc mailing list (firstname.lastname@example.org), or 2) make changes directly to the svn repository.
Primary Contact: Jeff Schering (jeffsch on irc channel #ubuntu-doc at irc.freenode.net). I also read the ubuntu-doc mailing list.
The html version is available from the DocteamProjects page.
You can get the entire style guide fileset (in DocBook xml format) from the docteam's svn repository. For help on how to get the files, see DocumentationTeam/Repository
To build your own html version of the style guide, at the command line change to the ubuntu-doc/generic directory and type make sg. The html files will be generated and placed in ubuntu-doc/build/generic/styleguide
jeff@cloud:~ $ jeff@cloud:~ $ cd ubuntu-doc/generic jeff@cloud:~/ubuntu-doc/generic $ make sg
You can then view the guide in your web browser by opening the file ubuntu-doc/build/generic/styleguide/index.html
If you have Apache FOP tools installed, you can generate a PDF of the styleguide. In the ubuntu-doc/build/generic/styleguide directory, type make sg-pdf.
To see the style guide in GNOME's help browser, change to the ubuntu-doc/generic/styleguide directory and at the command line type yelp styleguide.xml.
jeff@cloud:~/ubuntu-doc/generic/styleguide $ yelp styleguide.xml
Feel Free to Contribute
All comments, suggestions, and criticisms are welcome. The style guide is a document that all writers on the docteam must follow, so it's best if all members participate in its creation.
IMPORTANT: The style guide is in the Public Domain. If you are going to add content which is copied verbatim from another source, you MUST clear it with the original author(s) to make sure that they are willing to allow their work to go into the public domain.
Also, list your name with anything you contribute so we can add it to the Acknowledgements section of the style guide. Major contributors will be added as co-authors.
The style guide is split into several different sections, each in its own xml file. The main file is styleguide.xml.
- The introduction to the style guide. It describes what a style guide is, some of the goals, and also its applicability.
Filename in repository: introduction.xml
- Information Design
- Some advice on how to make your writing and presentation easy to read. Contributed by David Ottina.
Filename in repository: information-design.xml
- Document Structure
- Describes how Ubuntu docteam documents are structured. It discusses the contents of the preface and introduction. It gives the required and the optional parts of a document.
Filename in repository: doc-structure.xml
- Grammar, Punctuation, and Spelling
- Covers the grammar, punctuation, and spelling requirements for docteam documents. It also covers common mistakes and how to correct them.
Filename in repository: grammar.xml
- Commonly Confused Words
Lists and describes words which are commonly misused, such as affect/effect and than/then.
Filename in repository: confused.xml
- DocBook Conventions
Covers the DocBook elements used in Ubuntu docteam documents. It shows when to use article and book elements, and when and how to implement common features such as http links, screenshots, lists, tables, and so on.
Filename in repository: docbook-style.xml
- Writing for an International Audience
- Covers the style and type of language to use for internationalization (i18n) and localization (l10n). Contributed by Jerome Gotangco.
Filename in repository: international.xml
- Standard Terminology
- Covers the words to use when referring to Ubuntu, the GUI, and user actions.
Filename in repository: terminology.xml
- Word List
- A list of words which are not in most normal English language dictionaries, or which may be spelled differently in different dictionaries.
Filename in repository: wordlist.xml
- Reference Materials
- Contains a list of links and books that may be useful to writers and editors.
Filename in repository: reference.xml