<> ||<>|| = 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 [[https://wiki.ubuntu.com/DocumentationTeam/StyleGuide|Documentation Team's Style Guide]]. Also, please make sure to read through the [[http://library.gnome.org/devel/gdp-style-guide/2.20/gnome-glossary-desktop.html.en|GNOME desktop terms]] list, and the [[http://library.gnome.org/devel/gdp-style-guide/2.20/gnome-glossary-user-actions.html.en|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 [[http://doctormo.org/2009/03/16/linux-the-brand/|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: ||'''Label'''||'''Chapter'''|| ||`ch:prologue`||Prologue|| ||`ch:installation`||Chapter 1: Installation|| ||`ch:around-your-desktop`||Chapter 2: Around Your Desktop|| ||`ch:default-applications`||Chapter 3: Default Applications|| ||`ch:preferences-and-hardware`||Chapter 4: Preferences and Hardware|| ||`ch:software-and-packaging`||Chapter 5: Software and Packaging|| ||`ch:system-maintenance`||Chapter 6: System Maintenance|| ||`ch:command-line`||Chapter 7: The Command Line|| ||`ch:security`||Chapter 8: Security|| ||`ch:troubleshooting`||Chapter 9: Troubleshooting|| ||`ch:learning-more`||Chapter 10: Learning More About Linux|| ||`ch:credits`||Credits|| 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.