Ubuntu Manual Style and Content Guide

This is a draft style and content guide to help authors and editors working on the manual. For more general style help please refer to the Documentation Team's Style Guide. Also, please make sure to read through the GNOME desktop terms list, and the GNOME user action names list to make sure that you know how to refer to various UI widgets or actions.

Writing Style

Use of "Linux"

Where possible, avoid mentioning Linux and instead use Ubuntu. Treat Ubuntu and Linux as two different things, for one reason: Linux has a lot of bad connotations with ill-informed users, they believe that it's very hard, entirely command line based etc.

We should adopt what Canonical are doing with Ubuntu and are marketing it away from traditional Linux. See this blog post for more information.

Spelling

All Ubuntu documents in English use American spelling. Our manual follows the same convention.

Grammar and Formatting

Punctuation

Do not forget that in LaTeX, you need to use ` and ' for quotes. For double quotes, use `` and ''.

Use space, triple dash, space ( --- ) to connect two thoughts. For example:

• For many years, Linux was entirely command line based --- it didn't have a Graphical User Interface.

Formatting

When showing menu navigation, use the \nav command to add arrows (for example, \nav{Menu \then Submenu \then Submenu}). The arrows are added by the \then command.

If possible, try to avoid even arrow-based navigation. Instead, use bold fonts and say:

• On the Applications menu, click Accessories, and then click the Calculator item. This will start the calculator application.

To display terminal input/output (such as entering commands in the terminal), use the terminal environment:

\begin{terminal}
\prompt \userinput{sudo apt-get install banshee}
Password: \userinput{s3krE7}
Installing banshee...
Banshee has been installed.
\end{terminal}

The \prompt command will print the bash prompt ($) and the \rootprompt command will prompt the root prompt (#). The \userinput command formats the user's input so it's easily identified. For easy editing and debugging, the format currently sets the user input in red. This will likely change before the final release.

For inline code, use \code{this is inlined code}. You may use \prompt, \rootprompt, and \userinput inside the \code command as well.

To cross-reference or refer to another chapter, you may use the \chaplink command. Choose the label from the following table to pass to the \chaplink command:

For example, \chaplink{ch:installation} will produce "Chapter 1: Installation" and be hyperlinked to the first page of chapter 1.

Voice

Identity

Our manual is written by multiple people. Use the plural pronoun "We" when speaking on behalf of the group. Never use the singular pronoun "I".

We would like to carry on a conversation with the user. In writing, always address the user in second person, using the pronoun "you". For example:

• We recommend that you upgrade your installation of Ubuntu to the upcoming release.

Since our manual tries to steer the users into doing the right thing, we should not be commanding them what to do. It is best to say "we recommend you change..." or "we suggest you change..." instead of "you must change...", or just using the imperative "change ...". It is a good idea, however, to use the imperative in a list of steps.

Do not use third person, i.e. "Advanced users can...". Instead write "If you are an advanced user, you can..."

System's actions

When describing what the system will do, use "Ubuntu" to stand in for aspects of the operating system, Gnome, or other parts of the standard install that are not specifically branded applications. For example, when describing the Update Manager:

• When you click the Install Updates button, Ubuntu will download and install all of the recommended updates.

By attributing the action to Ubuntu, we remove the need for the user to learn that the Update Manager is a separate item that she must worry about. It is simply a title of the window.

On the other hand, some applications are well known or are explicitly named. For example, Mozilla Firefox, Pidgin, OpenOffice -- all are actors in their own right.

Marketing

Our manual is not marketing material. Try to avoid marketing speak:

• Wrong

  • Ubuntu is incredibly easy to install.

  Correct

  • Ubuntu is easy to install.

• Wrong

  • Ubuntu has an excellent feature...

  Correct

  • Ubuntu allows you to...

Content

Writing for newbies

We are writing for people who are new to Linux and Ubuntu, and perhaps even new to computers. We should assume that people have the skills of using the keyboard and mouse, and that they are generally aware of the multi-window desktop interface.

As such, we can give them directions to click on a menu (though we must point out where the menu is), click on the desktop, right-click on something, drag something around (though the first time we may want to explain this a bit), press combination keys (Ctrl-C), and be aware when windows or menus open or close.

Beyond that, any acronyms and technical terms need to be defined. Any widgets or buttons need to be pointed out at least once.

In general, assume that a user does not know their monitor from their computer, that the user does not understand the difference between memory and a hard drive, and that the user does not intuitively pick up these things unless we point them out.

However, also assume that a user is very interested in accomplishing certain tasks. A user wants to do the very basics on their computer: browse the Web, read and compose email, use instant messaging, create, manage, exchange, and edit various files (documents, images, audio, video).

A user is also interested in utilizing the full capabilities of their computer. The user wants to connect a printer, a webcam, an external drive or multiple monitors. The user may also be interested in lightly customizing their experience on their computer.

In writing for newbies, we need to be conscious of these desires. At the same time, we should also provide some ways for people to advance their skills: in-line sections for "advanced use" or "advanced users" may be a good way to provide additional detail without incorporating it into the main body.

Writing for users who are interested in using Ubuntu

Our audience is already engaged. The user has already picked up or opened the manual. She has scrolled or leafed to the page she is reading. If we must sell her on the benefits of Ubuntu then that's fine, but we must remember to get to the point quickly: there are many other places to compare and contrast between different operating systems or the free software advantage than the software manual.

Focusing on the core

While the Ubuntu universe has not just Ubuntu Desktop but also Kubuntu, Xubuntu, Edubuntu, the Netbook Edition, the Server edition, and other spinoffs, we are writing to the beginner audience. As such, we should restrict ourselves to the core Ubuntu Desktop product.

As such, all screenshots and instructions should be about this product only.

This does not preclude a short intro to other packages, and a separate (advanced) section describing the packages in more detail.

Names of things

Trademarks

For the first mention of some trademarked item, please use the full, correct name of the item and use the appropriate trademark signs. For future mentions of the same item, just use the full or common name of the item. For example:

• Microsoft® Windows® applications will not normally run on Ubuntu. In order to run Microsoft Windows applications, we recommend you install the Wine package from the Software Center.

Note that in LaTeX, ® is \textregistered and ™ is \texttrademark.

Ubuntu, and its components

Refer to https://wiki.ubuntu.com/DocumentationTeam/StyleGuide/StandardTerminology for information on what items in the GUI are called, and how to refer to Ubuntu.