Ubuntu Documentation Style Guide

Ubuntu Documentation Project

Disclaimer

Every effort has been made to ensure that the information compiled in this publication is accurate and correct. However, this does not guarantee complete accuracy. Neither Canonical Ltd., the authors, nor translators shall be held liable for possible errors or the consequences thereof.

Some of the software and hardware descriptions cited in this publication may from time-to-time be registered trademarks. Names of products and trademarks and trade protection laws and may thus fall under copyright restrictions. All trade names are subject to copyright restrictions and are registered trade marks of their respective owners. In citation of such names, Canonical Ltd. and contributing members of the Ubuntu Documentation Project essentially adhere to the manufacturer's spelling and in no way make claim to them.

THIS DOCUMENTATION IS PROVIDED BY THE AUTHORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License

This document is made available under a dual license strategy that includes the GNU Free Documentation License (GFDL) and the Creative Commons ShareAlike 2.0 License (CC-BY-SA).

You are free to modify, extend, and improve the Ubuntu documentation source code under the terms of these licenses. All derivative works must be released under either or both of these licenses.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE AS DESCRIBED IN THE DISCLAIMER.

Copies of these licenses are available in the appendices section of this book. Online versions can be found at the following URLs:

  • GNU Free Documentation License

  • Attribution-ShareAlike 2.0

Revision History
Revision 0.12005.05.31JS

Initial version of the Style Guide pre-release

Revision 0.22005.07.10JS

Added some content to punctuation section

Revision 1.02005.07.31JS

First relase version

Abstract

Style guide for the Ubuntu documentation team. The Ubuntu Documentation Style Guide is built with the participation of the members of the Ubuntu documentation team, and represents the current accepted practice for documents produced and maintained by the docteam. The guide is still missing a couple of items (marked TODO).


Table of Contents

Preface
Acknowledgments
1. Introduction
Overview of the Style Guide
Style Guide Applicability and Precedence
2. Information Design
Write to Facilitate Scanning
Match Writing Style to Purpose
Match Formatting to Importance
3. Grammar, Punctuation, and Spelling
Grammar and English
Punctuation
Apostrophe
Colon
Comma
Hyphen
Parentheses
Period
Quotation Marks
Semicolon
Spelling
4. Commonly Confused Words
5. Writing for an International Audience
Examples are universal
Use of numerals and figures
Using correct Terminology
Cultural considerations
6. Word List
7. Reference materials
Computer Related References
General Writing References

Preface

Table of Contents

Acknowledgments

Acknowledgments

This document is a collaborative effort of the Ubuntu documentation team. The authors of version 1.0. are listed below.

  • Jeff Schering

  • Jerome Gotangco

  • David Ottina

Chapter 1. Introduction

Overview of the Style Guide

A style guide is a reference tool used by writers and editors. It is an outline of the policies and standards that writers and editors are expected to work to.

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 style guide covers the entire spectrum of Ubuntu components.

The Ubuntu Documentation Style Guide is built with the participation of the members of the Ubuntu documentation team, and represents the current accepted practice for documents produced and maintained by the docteam.

This style guide attempts to achieve the following:

  • Help writers communicate clearly.

  • Create a consistent style across all documents.

  • Create a consistent use of terminology across all documents.

  • Highlight common problems in the use of the English language, and to provide solutions.

  • Help writers write for an international audience, including how to write for translation.

  • Help writers and editors select the appropriate DocBook markup.

This style guide contains three main types of information:

  1. Material that is unique to Ubuntu documentation.

  2. Material that may be helpful to writers, but is not covered in other guides.

  3. Material that is covered in other guides, but is either summarized or repeated here for convenience.

Style Guide Applicability and Precedence

The Ubuntu style guide is applicable to all documents produced by or for the Ubuntu documentation team. It covers all documents in the docteam's SVN repository.

The docteam may decide to take official responsibility for a limited number of important wiki pages; the style guide will be applicable to those pages.

The Ubuntu style guide takes precedence over all other style guides. Where there is a conflict between this style guide and any other style guide, the Ubuntu Documentation Style Guide shall prevail.

If you encounter a topic or situation that is not covered by this style guide, then refer to the GNOME Documentation Style Guide. If your document deals exclusively with KDE, then refer to the KDE Style Guide.

If you have still not found a solution after referring to one of the guides above, then you will have to make your own decision. See the Reference Materials section for links to other style guides and documentation handbooks.

Chapter 2. Information Design

Write to Facilitate Scanning

Users need to find information quickly. People don't read documentation as much as they scan it for solutions to their immediate problem. Writing and presentation styles that seem redundant in essays or other texts are often helpful to people scanning for information.

Readers can find and absorb information more quickly if documentation is clear, concise, and consistent. As well, translators can more easily translate documents with these attributes.

  • Writing must be clear: Write short, active sentences using everyday vocabulary. Maintain a visual separation between page elements.

  • Writing must be concise: Minimize content so it can be found and remembered. Keep pages short, modular and focused on a single topic.

  • Writing must be consistent: Refer to one thing or idea with the same word throughout the page. Use headlines, lists and emphasis to signal importance.

Match Writing Style to Purpose

Use a writing style that fits the text's purpose. The most useful styles in documentation are explanatory, procedural and descriptive.

Explanatory writing is used for special language or concepts that users need to understand a procedure. Format explanatory text in paragraphs.

Procedural writing is used for telling readers precisely what steps they must take to complete a task. Write procedural text as numbered lists. Tell users what to expect when they've finished.

Unlike the other two, descriptive writing is used primarily in reference material. It gives a short definition or identifies where a feature can be found. Lists and tables are useful in formatting descriptive text.

Chapter 5, Writing for an International Audience gives more guidance on writing style.

Match Formatting to Importance

Formatting text gives a visual hierarchy that lets users see the overall content of the page by scanning it.

Headlines summarize the topic of the underlying information. Scanning headlines gives the user an accurate picture of the detailed contents.

Lists allow users to skip over explanations they don't need and get straight to a solution.

Admonitions (callouts) package relevant information that doesn't fit into the primary flow of the topic.

Emphasis lets people pick words out of paragraphs, lists and examples; giving them an idea of the topic details before reading.

Formatting Conventions lists visual styles and their use.

Chapter 3. Grammar, Punctuation, and Spelling

TODO: Introductory text.

Grammar and English

TODO:

  • intro

  • parts of a sentence

  • use complete sentences

  • don't use run-on sentences (one idea per sentence)

  • one topic per paragraph

Punctuation

Much of this section may be obvious to most people, but it's important to clarify punctuation conventions to ensure that they are applied consistently across all documents. In addition, limits on the use of certain punctuation marks are imposed in order to ease document translation.

Apostrophe

  1. The apostrophe is normally used in forming contractions, but in technical documents which will be translated into languages other than English, try to avoid contractions. For example, use "is not" instead of "isn't"

  2. Avoid using the apostrophe to indicate possession. Instead, rework the sentence. For example, rewrite "The file's purpose is to store names and addresses." as "The purpose of the file is to store names and addresses."

  3. Do not use the apostrophe to form plurals of acronyms. For example, it is not "GUI's", but rather "GUIs".

  4. The apostrophe can be used to form plurals in certain cases where the lack of an apostrophe may cause confusion. For example, "1's and 0's"

Colon

  1. You can use a colon after the words "following" or "follows." For example, "Docteam members need to install the following packages: docbook, docbook-xsl, and subversion."

  2. Make sure that text preceding the colon is a complete sentence or a noun phrase. This is incorrect: "Before you try to install a web server, download: apache2, apach2-common, and apach2-doc."

  3. Use a colon after introductory text. For example, "You have only one option: Restart the computer."

  4. Do not use a colon in headings, or at the end of a procedure heading.

  5. Do not use a colon in a list that is introduced by "are" or "includes." This is incorrect: "The functions available in the calculator application include: addition, subtraction, multiplication, and addition."

Comma

The rules for comma use in normal prose are numerous and complicated. However, in a technical document intended for translation, sentences will tend to be shorter and simpler than in normal prose. As a result, comma use will also tend to be limited, and therefore, only some of the major points are covered here.

  1. Use the series comma. The series comma is the comma before the "and" in a list of three or more words or phrases. Example: "The functions available in the calculator application include addition, subtraction, multiplication, and addition."

  2. Use a comma to set off "for example" and similar words and phrases such as "namely" and "that is" For example, you can find many examples of this type of comma use in the style guide.

  3. Use the comma after introductory phrases and clauses. Example 1: "To open your browser, click on the Firefox icon." Example 2: "A few minutes after starting your computer, the login screen will appear"

Hyphen

  1. Use a hyphen in compund modifiers preceeding a noun. Example: "Evolution is an end-user application."

  2. Use a hyphen in spelled-out fractions, unless the fraction is at the start of a sentence. Example: "Well-written documentation is one-half of a successful software application."

  3. Use a hyphen in compound words formed with "better", "best", and "well", unless they are already modified. Example: "Subversion is a well-known version control system. It has very well written documentation."

Parentheses

  1. Use parentheses around abbreviations and acronyms that you will use later. Example: "The Ubuntu Documentation Project (UDP) is an important piece of the Ubuntu GNU/Linux distribution."

  2. Do not use parentheses to set off an explanation or an aside. For example, do not write a sentence (like this one) that uses parentheses in this manner.

Period

  1. Use a period to end sentences.

  2. End abbreviations with a period. (eg. abbrev.)

  3. Use a period at the end of each step in a procedure.

  4. In lists, use a period only if the list items are complete sentences.

Quotation Marks

  1. Use quotation marks around material that is repeated verbatim from another source, when the length of the copied material is such that it can be included "inline" with the paragraph.

  2. Use quotation marks around letters, words or phrases that you want to emphasise without using italics or bold text.

Semicolon

The semicolon is frequently misused, so it's best to avoid it. A sentence with a semicolon can usually be split into two or more sentences. Splitting the sentence will make it easier to read and translate.

Spelling

American English. Use standard American English spelling in all Ubuntu English language documents.

Dictionary (for spelling only). There is a great deal of agreement among American English dictionaries when it comes to spelling, so for the purposes of Ubuntu technical documents, you can use any American English dictionary that is convenient. You can use the built-in spellchecker of whatever editor you are using, provided that it is set to American English. Places where there are conflicts (such as "email" versus "e-mail") are handled by the word list (see Chapter 6, Word List). If you find a spelling conflict that is not in the word list, then please let us know what the word is along with your recommendation for the version to use. There is a list of online and printed dictionaries in the Reference Materials section.

Compound Words. In technical documentation, two-word compounds tend to get converted over time, first into hyphenated compounds, and then into single word compounds. For example, "on line" became "on-line", and is now gradually becoming "online". In general, use the one-word compound for Ubuntu documentation. However, there are several exceptions to this rule. If you are not sure of a particular word, then check the word list. See Chapter 6, Word List

Chapter 4. Commonly Confused Words

There are many words in the English language which cause problems for writers of all skill levels. Some of the more common ones are listed below.

accept, except

Accept means to agree to, or to receive. Except means to exclude or to leave out.

advice, advise

Advice is an opinion about what should be done about a problem or situation. Advise is a verb, meaning to give advice to.

affect, effect

Affect is a verb meaning to influence. An effect is a result, outcome, or consequence of an action or event.

a lot, allot

A lot is a two-word phrase meaning a great deal or a large amount. It is never "alot." Allot means to give out or to allow to have.

assure, ensure, insure

Assure means to make a promise or commitment. Ensure is to make certain or to make secure. Insure means to provide or obtain insurance.

a while, awhile

The two-word phrase a while is a noun, and functions as a subject or an object in a sentence. Awhile is an adverb meaning for a short time. Awhile is never preceded by a preposition; in that case use the two-word form. For example, you can stay awhile, or you can stay for a while.

complement, compliment

As a noun, complement is something that completes or make makes up a whole, or brings to perfection. As a verb, complement means to complete. Compliment means to praise, and as a noun, it is an expression of praise.

Examples: Documentation complements a software application. The supervisor complimented her employees on their work.

everyday, every day

The single word everyday is an adjective, and means "daily" or "normal." The two-word phrase every day is an adverbial phrase, and is used only to modify verbs.

Examples: Writing is an everyday occurrence. I wrote something every day last week.

fewer, less

Use fewer for nouns that can be counted: fewer words, fewer ideas, fewer people. Use less for collective nouns: less money, less hair, less work.

good, well

Good is an adjective, and well is an adverb

Examples: The employees did a good job. (good modifies the noun job) The employees did their job well. (well modifies the verb did)

its, it's

Its is the possessive form of the pronoun "it." It's is a contraction of "it is" or "it has."

Examples: The dog ate its food. It's a good day to write.

principal, principle

Principal is generally used as an adjective, and means "chief," "leading," or "primary." Principle is a noun only. In a technical writing context, principle is typically used to describe a basic or fundamental mode of behaviour of a system or machine.

Examples: The automobile is the principal means of transportation in North America. You must understand a machine's principle of operation before writing the manual.

rational, rationale

Rational is an adjective, and is used to indicate that something is based on reason or is logical. Rationale is a fundamental reason or basis.

Examples: The team made a rational decision. The rationale for the team's decision was explained to the manager.

than, then

The most common mistake made with these words is to use then in place of than. Only use then when describing something that comes next in order. Use than in comparisons.

Examples: Working with XML can be more useful than working with HTML. I wrote the standards then uploaded them to the web site.

their, there, they're

Their and there are frequently used incorrectly, despite having distinctly different meanings. Their is used to indicate possession or ownership, and there is used to indicate position or to introduce a clause or sentence. They're is simply the contraction of "they are."

Examples: The writers left their pens at home. There are writers over there. They're discussing their lack of pens.

to, too, two

The most common error here is to use to in place of too. Too means "also," "in addition," or "more than enough." Use to in all other cases. Two is the number "2."

Examples: I went to the store too. There are too many writers in the room. There are two writers in the room.

your, you're

Your is used to indicate possession or ownership, and you're is the contraction of "you are."

Examples: You're driving your car to the store.

Chapter 5. Writing for an International Audience

How to write for internationalization (i18n) and localization (l10n)

Examples are universal

When writing, there are times that you need to use examples to explain a subject matter. Always make it a rule that examples should be universal - regardless of the written language, the example will be understood by any reader. To make your examples "universal," here are some tips that can help you:

  • When using screen captures, be consistent in their look and feel. If there is no localized equivalent of the screen capture, chances are, your sample will be used.

  • Make your subjects simple. For example, a name like "Joe" is likely to be more familiar to everyone instead of "Pyotr" or "Shigetaka".

  • Consider the cultural differences between nations when making examples. Refer to the section called “Cultural considerations” for guidelines.

Use of numerals and figures

The improper use of Numerals and figures can provide the most confusion when translated to another language. Numerals are very important when it comes to measurements and even simple figures like date and time can have big differences between countries.

When writing dates, remember that different cultures have different ways of describing it. Therefore, you may want to consider the following conventions in writing dates:

  • Use the correct date convention for your audience.

  • When writing days and months, do not abbreviate these words. This will prevent confusion when translation work has begun on the finished document.

  • Consider adding a small note in the document about the date convention being used.

When there is a need to write the time, it is better to write it in a 24 hour format. You should inform your audience the timezone and naming convention being used.

Using correct Terminology

Terminology is an area of writing that can cause a lot of confusion among translators. The following guidelines may help you prepare a language-friendly document suitable for translation.

  • Choose words with one or very few meanings.

  • Use simple verb forms in writing. Most verbs in the simple form will likely have an equivalent in another language.

  • Do not use terms that are jargon or slang.

  • Whenever necessary, define all special and technical terms in a glossary section of your document.

  • Choose words that are easy to pronounce. Not all readers of your piece are native english speakers.

  • Limit difficult words to technical terms so as not to slow down your audience when reading.

  • Expressions for time, place and relationship should be as simple as possible.

  • Always make sure your spelling is correct! Use a spellchecker and a dictionary when in doubt.

Cultural considerations

When writing documentation, always keep in mind that your work might be translated to another language. Because of this, you have to consider cultural differences on a global scale. Names, places, events, and actions should be chosen as carefully as possible when they are to be used in your work so as to avoid misunderstanding between parties concerned. Consider the following guidelines when writing:

  • Do not use names of places, events, and actions that are historically bound to certain countries and their cultures. Some people may find it offensive for various reasons. The same applies to the use of religious references as it may inject a clash of beliefs among readers of your work.

  • Informal expressions must be avoided at all times and may only be used when absolutely necessary. The end product of a translated document filled with colloquial and vernacular languages and expressions would make no sense at all.

  • Date and time is expressed differently in many countries. You may consider writing them in the ISO 8601 standard method and indicate the conventions used in your document so that the translator can easily adjust the text to be translated.

Chapter 6. Word List

- B -
- S -
Backspace key- K -
backup (n) Samba
back up (v)K Desktop Environment (KDE)screen dump
bandwidthkeycodescreensaver
bitmapkeypadscreenshot
Bourne-again shell (bash)keystrokescrollbar
Bourne shellkeywordserver side (n)
braces ({ and })kHzserver-side (a)
brackets ([ and ])Korn shellset up (v)
built-in (a, n) setup (n)
- L -SGML
- C - shell
left-handShift key
cannot (one word only)left-mostsingle-precision (a)
Caps Lock keyleft sidesingle quote
CD-ROMless-than signsource code
C language (n)line-feed (a)spacebar
C-language (a)linefeed (n)spellcheck
check boxLinuxspellchecker
client side (n)loginsquare brackets ([ and ])
client-side (a)logoutstandalone
command line (n)lower-casestart tag
command-line (a)lower-rightstatus bar
compile time (n) stylesheet
compile-time (a)- M -SuSE Linux
compact disc (music) swapfile
cross-referencemanpage
C shellmarkup- T -
Ctrl keymenu bar
Ctrl-Alt-DeleteMHzTab key
curly bracketsmultilineTelnet (n)
multimediatelnet (v)
- D -mulitusertext box
time zone
Delete key- N -titlebar
DocBook toolbar
double-clicknameservertookit
down arrownamespacetool tip
downloadnewlinetop-level (a)
drag-and-dropnewsgrouptroubleshoot
drop-down (a)non-breaking
nonlocal- U -
- E -nonstandard
non-validatingUniversal Serial Bus (USB)
Emacs up arrow
email- O -uppercase
end-of-file (EOF) upper-left
end userofflineup-to-date
End keyoffloadUSA
Escape keyOgg VorbisU.S.
onlineusername
- F -open source
- V -
file manager- P -
filename versus (avoid vs.)
file serverparenthesis (singular)vice versa
filesystemparentheses (plural)
file typepassword- W -
forefroundpathname
frontendpattern-matchingthe Web (n)
FTP (protocol)peer-to-peerweb (a)
FTP sitePlug and Play (PnP)web client
plug-inwebmaster
- G -Point-to-Point Protocol (PPP)web page
popup menuweb server
GHzPortable Document Format (PDF)web site
GIMPPortable Network Graphic (PNG)whitespace
GNU Public License (GPL)POSIX-compliantwildcard
greater-than signPost Office Protocol (POP)Windows 98
GUI, GUIsPostScriptWindows 2000
progress barWindows NT
- H -public key (n)Windows XP
public-key (a)workaround
hard diskpull-down (a)workstation
high-level (a) World Wide Web (WWW)
home page- Q -wraparound
hostname write-only (a)
Howto (in titles)WYSIWYG
howto (in text)WYSIOO
HTML
HTTP- R -- X Y Z -
hypertext
random-access (a)X client
- I -read-only (a)X server
read/writeX Window System
inlinereal-time (a)x86
InternetRed Hat LinuxxFree86
Return keyXHTML
- J -right-clickXPath
right-handXPointer
JavaScriptroll back (v)XSL
Java™ (first use)rollback (n)XSLT
Java (subsequent use)runtime 

Chapter 7. Reference materials

Other style guides and the like

Computer Related References

Gnome Documentation Style Guide

http://developer.gnome.org/documents/style-guide/

The KDE Style Guide

http://i18n.kde.org/doc/styleguide/index.html

The KDE DocBook Author's Guide

http://i18n.kde.org/doc/markup/index.html

LDP Author Guide

http://www.tldp.org/LDP/LDP-Author-Guide/html/index.html

Fedora Project Documentation Guide

http://fedora.redhat.com/participate/documentation-guide/

Grammar, Punctuation, and Capitalization: A Handbook for Technical Writers and Editors

http://stipo.larc.nasa.gov/sp7084/index.html

O'Reilly Default Stylesheet and Word List

http://www.oreilly.com/oreilly/author/stylesheet.html

General Writing References

Online Writing Lab

http://owl.english.purdue.edu/