StyleGuide

Differences between revisions 2 and 3
Revision 2 as of 2007-10-29 21:22:21
Size: 22394
Editor: 79-72-96-161
Comment: miscellaneous tidying
Revision 3 as of 2007-10-30 08:15:20
Size: 23412
Editor: 79-72-96-161
Comment: importing section which didn't get imported by docbook2moin
Deletions are marked like this. Additions are marked like this.
Line 101: Line 101:
intro; terminology may seem tedius to learn, but if you want to avoid problems and make your writing clear and understandable to your audience, then you will want to learn them.

 1. parts of a sentence
 1.
 1.
 1.
 1. one topic per paragraph

Terminology may seem tedius to learn, but if you want to avoid problems and make your writing clear and understandable to your audience, then you will want to learn them.

 1. '''Parts of a sentence'''
 1. '''Subject and Predicate''' - A sentence has two main parts; a subject and a predicate. The subject is the person or thing that you are talking about. The predicate is what you are saying about the subject. Without a subject and predicate, there is no sentence.
 1. TODO '''Clauses''' - stuff about main and subordinate (independent and dependent clauses), what they are, how to distinguish between the two types, and so on and so forth.
 1. '''Run-on Sentences''' - do not use run-on sentences. Run-on sentences are actually two main clauses run together into one sentence and separated by a comma. You can correct a run-on sentence in more than one way.
  ||Wrong||There are also quite a few terminal-based editors available in Ubuntu, popular ones include VIM and Emacs||
  ||Correct||There are also quite a few terminal-based editors available in Ubuntu. Popular ones include VIM and Emacs.||
  ||Correct||There are also quite a few terminal-based editors available in Ubuntu; popular ones include VIM and Emacs.||
 1. '''One topic per paragraph'''

Introduction

This document is the 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).

Acknowledgments

This document is in the Public Domain.

This document is a collaborative effort of the Ubuntu documentation team. The contributors are:

  • Jeff Schering
  • Jerome Gotangco
  • David Ottina

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 Documentation Team's [:DocumentationTeam/Repository:repository].

The docteam also takes care of the [https://help.ubuntu.com/community documentation wiki]; the style guide is also applicable to those pages.

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.

Information Design

Define Your Audience

TODO: Importance of knowing who you are writing for.

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.

The section 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.

Document Structure

TODO: How Ubuntu docteam docs are structured

Grammar, Punctuation, and Spelling

TODO: Introductory text.

Grammar and English

Terminology may seem tedius to learn, but if you want to avoid problems and make your writing clear and understandable to your audience, then you will want to learn them.

  1. Parts of a sentence

  2. Subject and Predicate - A sentence has two main parts; a subject and a predicate. The subject is the person or thing that you are talking about. The predicate is what you are saying about the subject. Without a subject and predicate, there is no sentence.

  3. TODO Clauses - stuff about main and subordinate (independent and dependent clauses), what they are, how to distinguish between the two types, and so on and so forth.

  4. Run-on Sentences - do not use run-on sentences. Run-on sentences are actually two main clauses run together into one sentence and separated by a comma. You can correct a run-on sentence in more than one way.

    • Wrong

      There are also quite a few terminal-based editors available in Ubuntu, popular ones include VIM and Emacs

      Correct

      There are also quite a few terminal-based editors available in Ubuntu. Popular ones include VIM and Emacs.

      Correct

      There are also quite a few terminal-based editors available in Ubuntu; popular ones include VIM and Emacs.

  5. 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.
  2. Avoid using the apostrophe to indicate possession because it can cause problems when your text is being translated into a different language. Instead, rework the sentence so that an apostrophe is not needed.
  3. Do not use the apostrophe to form plurals of acronyms.
  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. In the example below, a colon is not needed after "download"
  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 "include."

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

Hyphen

  1. Use a hyphen in compound 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 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

<formalpara><title>American English</title>Use standard American English spelling in all Ubuntu English language documents.

</formalpara><formalpara><title>Dictionary (for spelling only)</title>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 <xref></xref>). 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.

</formalpara><formalpara><title>Compound Words</title>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 <xref></xref>

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

DocBook Conventions

TODO:

  1. How DocBook tags are used

  2. When to use a DocBook article, and when to use a DocBook book.

  3. How to markup screenshots and other graphics, sections, cross-refs, tables, etc.

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 <xref></xref> 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.

Standard Terminology

General

How to refer to Ubuntu

  1. Use "Ubuntu operating system" the first time you refer to Ubuntu, then use "Ubuntu" thereafter. You can use the terms "Ubuntu system" and "Ubuntu environment" when they are more appropriate than "Ubuntu operating system."
  2. You can use "Ubuntu Linux distribution" or "Ubuntu Linux distro," but try to reserve those terms for audiences who do not need to have "distribution" or "distro" explained to them.
  3. You can use Kubuntu, Kubuntu system, Kubuntu environment, and Kubuntu distribution when referring to Ubuntu with the KDE desktop, but remember that it is still the Ubuntu operating system, not the Kubuntu operating system.
  4. Use "based on Debian GNU/Linux" when referring to Ubuntu's Debian roots.
  5. Use "Linux-based" when referring to Ubuntu's kernel roots.
  6. You might find that you must use the term "Ubuntu Linux". If so, then try to work in the phrase "based on Debian GNU/Linux".
  7. If you use any of these terms, (Debian, GNU/Linux, Linux, distribution, distro) you must explain them in the text following their first use, as well as in the glossary (if there is a glossary). The only exception is when the audience of the document is already knowledgeable about the terms.
  8. If there is an About Ubuntu section in your document, then describe Ubuntu and its genealogy, including GNU/Linux, Debian, and the Linux kernel.

GUI Terms

TO BE IMPORTED

User Actions

Random notes: Select vs highlight vs choose. Select an item from a list, choose an item from a menu. To choose an menu item, click on it. Do not use highlight as a verb; use as a noun or adjective. The selected text is highlighted.

Word List

TO BE IMPORTED

Reference materials

Other style guides and the like

General Writing References

DocumentationTeam/StyleGuide (last edited 2014-07-02 23:40:07 by bregma)