StyleGuide

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.

Contents

  1. Document Plan for the Style Guide
  2. Current Version
  3. Feel Free to Contribute
  4. Document Outline

Document Plan for the Style Guide

  1. 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.

  2. Document Outline: See the Document Outline section below.

  3. Target Presentation Formats: html, pdf

  4. License: Public Domain

  5. Technologies and Techniques: The style guide is in DocBook xml, and stored in the docteam's Subversion repository.

  6. Release Target: Version 2.0 of the guide will be release in April, 2006.

  7. 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)

  8. How to Contribute: There are two ways to participate: 1) send an email to the ubuntu-doc mailing list (ubuntu-doc@lists.ubuntu.com), or 2) make changes directly to the svn repository.

  9. Primary Contact: Jeff Schering (jeffsch on irc channel #ubuntu-doc at irc.freenode.net). I also read the ubuntu-doc mailing list.

Current Version

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

Example: 

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.

Example: 

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.

Document Outline

Introduction
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

CategoryDocteam

StyleGuide (last edited 2008-08-06 16:28:08 by localhost)