Style Guide

From The Document Foundation Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.


Contributors’ Guide
Chapter 4 Style Guide

for LibreOffice.org User Guides

Introduction

Follow this guide when writing or editing chapters for the User Guides for LibreOffice 3.x, to help ensure a consistent and professional image for the guides.

For the most part, the suggestions provided in this document are guidelines, not rules. Use your own judgment in applying them, and ask others for input if you’re not sure what to do. This guide does contain a few “rules” that must be followed to ensure consistency across all chapters. These are indicated with a star in the margin: Star.png

Related sources of information

The following documents are recommended as a complement to this style guide:

  • The Chicago Manual of Style. University of Chicago Press.
  • Read Me First! A Style Guide for the Computer Industry. Sun Microsystems.
  • The Modern Language Association (MLA) guidelines.

For computer terminology and acronyms, see the Sun Global Glossary, http://download.oracle.com/docs/E19957-01/805-4369/, available to read online. Design information (what chapters should look like, including an explanation of when to use each custom LibreOffice style for paragraphs, characters, pages, frames, and numbering) is located in the LibreOffice Chapter Template, the LibreOffice Book Template, and Chapter 6 of this Contributors’ Guide.

Writing style

The following list summarizes our preferred writing style. Some of these points are discussed in more detail in the tips for writers, reviews, and editors starting on page 6.

  • Use short, simple, easy-to-understand words and sentences. Be concise and clear.
  • Write in active voice, using passive voice only when necessary or appropriate. A case of appropriate passive voice is when the focus of the sentence is on the receiver of an action whose doer is obvious or is not important. For example, The File dialog box is displayed is OK.
  • Use the present tense, using future tense only when necessary or appropriate. Try to make your descriptions timeless. For example, write The File dialog box is displayed, rather than The File dialog box will be displayed. Use future tense only when one event is necessarily later than another. For example, If you use styles, your documents will be easier to maintain.
  • Avoid over-using you. For example, instead of saying if you want to have table headers repeat on a new page, you need to do yyy, say to have table headers repeat..., do yyy.
  • When appropriate (as in instructions), use the imperative mood. For example, instead of you should not use slang, say do not use slang.
  • In circumstances where the only alternative to you is the passive voice, use you. For example, instead of in this window xxx can be done, say in this window you can do xxx.
  • Use gender-neutral language, but don’t use awkward phrases like he or she to do so. See page 8 for some examples.

Variations of English

For consistency, when writing the user guides we are following US English spelling conventions and UK English punctuation conventions. See also “Punctuation” on page 6.

You can use other spelling or punctuation conventions when writing other documents.

Writing for an international audience

Remember, when writing the user guides, you are writing for an international audience. Here are some things you should keep in mind.

Date formats

Does 3/12/99 mean March 12, 1999 or 3 December 1999? Always spell out part or all of the month. Use formats like December 3, 1999 or 3 Dec 99.

Time

Express time in the 24-hour format: 08:00, 18:00.

Seasons and holidays

Seasons have different meanings in different parts of the world. For example, summer is January in the southern hemisphere. Also, not everyone knows when Thanksgiving or Boxing Day are (or the date varies from one country to another). Therefore, it is better to state the name of a month or use “first quarter” or similar.

Colloquial language and culture

Avoid colloquialisms and slang. A remark that is natural to you may be incomprehensible (or offensive!) in a different cultural context. Similarly, avoid references to sporting events or local customs when such a reference carries part of the explanation.

Plain English

“Plain English” does not mean “dumbed down”. The principle of Plain English is to use words that your audience understands and to use them consistently. Avoid technical jargon, and avoid using multiple terms to refer to the same thing or the same term to refer to multiple things.

Humor

Use humor with caution, because much humor is culture dependent, and therefore you risk offending the audience. If nothing else, it distracts the reader from your message.

Abbreviations and acronyms

Technical abbreviations and acronyms are encouraged, but their meaning must be made clear. To introduce an acronym, spell out the full term, followed by the acronym in parentheses. For example, Application Program Interface (API).

Avoid i.e., e.g., and etc.

Many writers use Latin abbreviations incorrectly. Even if you understand these terms, your audience might not. Hence, their use is counter to the principle of Plain English. Find a way to write your sentence without using these terms. Here is a list of equivalent English phrases:

Latin Abbreviation English Equivalents
i.e. That is; specifically
e.g. For example; such as
etc. And so on; and so forth

Definitely do not use less common Latin abbreviations like cf. and q.v.. Spell out vs. as versus; better still, revise the sentence to avoid its use.

Commonly used words

Following is a partial list of commonly used technical terms and their correct structure. See also “Preferred terminology” on page 12.

AutoCorrect backup (adj. or n.) back up (v.) bitmap checkbox
database dial-up (adj.) disk drop down (v.) drop-down (adj.; do not use as a noun)
email file name gateway hard disk hardware
how-to IssueZilla JavaScript keyboard metadata
multitasking online LibreOffice open source overwrite
password plug in (v.) plug-in (adj. or n.) pop up (v.) pop-up (adj; do not use as a noun)
PostScript program software source code StarOffice
subdocument toolbar website

Star.pngCapitalization

Use sentence-style capitalization for all headings. Also capitalize the following items in sentence style:

  • Specific cross-references in text, for example, Table 1, Note 2, Figure 5
  • Captions for figures and tables
  • Column and line headings in tables
  • Bulleted and numbered list entries

Star.png Cross-references

For cross-references to headings and figure/table captions within the same chapter, always use Writer’s cross-reference feature (Insert > Cross-reference). Never type the text, and do not use hyperlinks. When inserting cross-references to figures and tables, choose “Category and number” for the type of reference. You can also type the word “Figure” or “Table” and insert the number as a cross reference, choosing “Numbering” as the reference type; this is useful for phrases such as “see Figures x and y” (instead of “see Figure x and Figure y”).

Star.png Formatting conventions

GUI elements

Make sure that the names of user interface items (menus, icons, options, dialog boxes, and windows) match what appears in the application.

Headings, titles, and subtitles

Use “sentence style” capitalization for headings. That is, capitalize only the first letter of the heading plus any terms that would normally be capitalized in text.

Use parallel construction for headings at the same level. For example, headings on the first level generally use a gerund like Installing.

Do not number headings.

Use “headline style” capitalization (also known as “title case” and “initial caps”) for chapter names (titles) and subtitles. That is, capitalize the first letter of each word except for certain small words, such as articles and short prepositions, the word to in an infinitive phrase, and case-specific product names.

Key commands

Use the OOoKeystroke character style.

Capitalize command keys (Tab, Caps, Control, Shift) and letter keys.

If two keys must be pressed at the same time, denote that with a + sign. If the combination requires a command key and a letter key, place the command key first. Example: Control+K. No space before or after the + sign.

Lists

Finish a list introduction with a colon (:). List introductions can be either full sentences or sentence fragments. Some style guides differentiate between the two types and require different ending punctuation (or none at all); others, like this guide, do not make this distinction. Note, however, that if the last sentence before a list does not directly introduce the list, end that sentence with a period.

Guidelines for constructing list items:

  • Capitalize the first word of each list item.
  • In a list of complete sentences, use punctuation at the end of each list item.
  • In a list of sentence fragments, use no punctuation at the end of each list item.
  • Avoid mixing complete sentences and sentence fragments in the same list.

Menu paths

Use the OOoMenuPath character style. For multi-level menus, use “>” between the names of the submenus, with a space on each side of it. For example: View > Toolbars > Object Bar.

Write the titles of the menus as they are seen on the screen (include appropriate capitalization). However, do not include any trailing ellipsis (for example, refer to a menu item labelled “Preferences...” as simply “Preferences”).

Procedure descriptions

To describe single procedures, use menu items. If readers can perform a procedure in more than one way and if it is easier to use the context menu or to click an icon you can point to it with a tip, after the procedure description. Shortcuts are treated in special topics.

Number the procedure steps, but try to limit the number of steps to a maximum of ten.

Make each step short and equivalent to one action, so a user can more easily follow a procedure. Exception to this rule: You conclude a step with "and press OK".

Provide short explanatory text and visual cues. Tell readers what is to happen after a step.

Tips, Notes, and Cautions

A Tip describes practical but nonessential information that does not otherwise fit into the flow of the text, for example a keyboard shortcut or an alternative way to perform a step in a procedure.

Use a Note to break out related, reinforcing or other special information, for example an explanation or comment.

A Caution is mandatory text that you must provide to protect the user from injury or the hardware/software from damage. Insert the Caution before the information that might cause the potential hazard. First, describe the potential hazard to data, equipment, or personnel. Then, describe the actions that are required to avoid the hazard.

Keep the text of Tips, Notes, and Cautions short and relevant.

The main subject should cover the main part of the topic.

Try to limit the number of Notes, Tips and Cautions to approximately two on a page.

If necessary, reorganize the text to reduce their number.

Graphics and images

See Chapter 2, Producing LibreOffice user guides, for technical information on inserting, anchoring, and creating captions for graphics.

Star.pngUse the US English version of LibreOffice for all screen captures. The British version has some differences that can lead to inconsistency and occasional confusion in the user guides.

Use the Galaxy icon set, which may not be the default on your operating system.

Avoid screen captures from Microsoft Windows, unless you need to show a Windows-specific feature. If you are cropping to show only a portion of a dialog box, any o/s may be used.

Use the LibreOffice dialog boxes, not operating system-specific ones, when possible. This setting is found in Tools > Options > LibreOffice > General, select Use LibreOffice dialogs in the Open/Save dialogs section.

Star.png File formats

Use the PNG or BMP format for screenshots and JPEG for photos. When in doubt, use PNG. (LibreOffice saves BMP images as PNG.)

Color choice

All graphics must be easily readable when printed in black and white. This is especially important when creating pie charts and graphs that normally use color.

Size and cropping of screen captures

Show only what is required to illustrate your message; crop (cut off) unnecessary parts of screen captures.

When possible (without degrading the image), keep the width of screen captures under 15 cm (5.9 inches).

Captions

  • Images, figures, tables, and the like should have captions, with these exceptions:
    • When a figure is located within a table and the adjacent cell in the table explains the figure.
    • When a figure (such as a picture of a toolbar) follows closely after a heading that describes the figure.
    • When the graphic is very small (such as an icon) and is within or beside text that describes it.
  • Use the caption feature in Writer for greater consistency.
  • Star.pngCaption rules:
    • Label images, figures, and drawings “Figure”, not “Illustration” or any other name.
    • Position captions below images, figures, and drawings, and above tables.
    • Number all figures that have captions. Use a number range variable; never type figure or table numbers. Writer’s caption feature applies number range variables automatically.

Star.png Punctuation

In the few cases where US English and British English punctuation conventions differ, use British English because it is more logical. For example, periods and commas generally go outside, not inside, a closing quotation mark. Often you can revise the sentence to not require the quotation marks or put the quoted material in italics (OOoEmphasis character style).

Writing style (tips for authors, reviewers, and editors)

This section provides suggestions for improving your work as an author, reviewer, or editor of LibreOffice user guides. The terms reviewer and editor are used mostly interchangeably in this document. In traditional corporate technical publishing, an editor is one type of reviewer; another type of reviewer is a subject matter expert, who verifies the technical correctness of a document. In the volunteer, open source world of LibreOffice, the same person often fills both of those roles.

Views of a document

You can view a document in roughly three different ways:

  • Content: Does the application actually work the way the document says it does? Are the features described completely and correctly?
  • Structure: Does the organization of the document make sense? Do the explanations make sense? Are the diagrams clear? Is there a better way to explain a particular concept?
  • Format: Does the document have proper usage, grammar, and punctuation? Does it use the template and styles appropriately?

When people think of editing, they normally think of copy-editing, which corresponds to the format view. But reviewing the content and reviewing the structure (also called substantive editing) are important and necessary components for a project like the User Guide project. And of course, authors need to be concerned with all three aspects of their documents.

Content

Try to verify the technical facts presented in the document. In a few cases, this might require doing research (such as asking developers for information). However, in most cases, you can check the correctness of the facts yourself by using the application.

  • Do the names of user interface items (menus, icons, options, dialog boxes, and windows) match what appears in the application?
  • Do the steps of procedures match what happens in the application?
  • Are any steps missing?
  • Is the level of detail appropriate for the typical user (neither too much nor too little)?

Structure

Check the structure of the document. Is the document structure clear? Is anything missing that should be covered? Does the explanation make sense? Is this diagram clear? Is there a better way to explain this concept?

When possible, reviewers should add new material or revise existing material, not just say, “This needs work.” However, if you have questions (for example, if something is unclear) and you don’t know the answer, then pointing out the problem is still useful.

Alternatives to prose

Traditional prose is not always the best way to convey a concept (even when it is well written). Some alternatives to consider are:

  • Bulleted and numbered lists.
  • Tables and matrices.
  • Diagrams, flowcharts, and logic trees.
  • Pictures and graphics.

You are probably familiar with these concepts. Hence, they won’t be discussed here except for a brief note on the difference between bulleted and numbered lists:

  • Numbered lists are used for a sequential series of events or actions. For example, listing a step-by-step procedure.
  • Bulleted lists are used for non-sequential lists. For example, listing different ways to perform a task, or also a series of actions that need not be performed in any particular order.

The following examples illustrate the use of some of these alternatives.

Example of standard prose

The peer review process is very important for the LibreOffice user guides. A document starts its life as “visible”. This means that the author is working on it. When the author wishes a review, the author selects state > submit. Next, a reviewer downloads the document and performs edits. When the edits are done, the reviewer uploads the edited file to the appropriate feedback folder. The reviewer then informs the author, through the list.

Example of bulleted and numbered lists

The peer review process is very important for the LibreOffice user guides. Peer review involves the following stages:

  1. A document starts its life as “internal draft”. This means that the author is working on it.
  2. When ready for review, the author submits the document (state > submit for publication).
  3. The reviewer “retracts” the file (setting the state back to “internal draft”), downloads the file, and performs edits. When done, the reviewer will:
    • Upload the edited file to the appropriate feedback folder
    • Inform the author, through the list

Diagrams, flowcharts, and logic trees

A well-designed diagram can significantly add to an explanation. Consider this example:

Figure 1. The peer review process.

Notice that in this example the diagram does not contain all the information needed to complete the process (for example, “where do you upload the file?”). Hence, this diagram would be used in addition to another form of explanation.

Gender-neutral language

Using gender-neutral language is not simply a matter of “political correctness”. Our goal is to convey information in a clear, understandable form. If the document is ambiguous, offensive, or frustrating to part of your audience, that will interfere with clear communication. Using gender-neutral language does not mean that one must use incorrect grammar, awkward phrases (like he or she), or non-words like s/he. Incorrect or contrived phrases are neither the goal, nor the outcome of gender-neutral writing.

What not to do

  • Do not use he as a generic pronoun; use it only to refer to men and boys.
  • Do not use she as a generic pronoun; use it only to refer to women and girls.
  • Do not use they as a singular pronoun. This usage is gaining acceptance, but it is widely viewed as incorrect.
  • Avoid phrases such as he or she and he/she or made-up words like s/he.
  • Do not use a feminized noun (like manageress) when the normal noun (manager) covers both sexes.

What to do

With what not to do in mind, here are some techniques you can use:

Bypass the problem of gender whenever possible. For example, when writing procedures and instructional material, you are usually speaking directly to the reader, so you can use:

Imperative mood (Do this.). Second person (you) instead of third person (he, the user).

Imperative mood:

No To log in, the user must enter his login name and password.
Yes To log in, enter your login name and password.

Avoid pronouns completely when possible. Try these techniques:

Repeat the noun (sometimes this also makes your meaning clearer):

No Technical documentation exists for the reader. You are writing it for him, not for your ego.
Yes Technical documentation exists for the reader. You are writing it for the reader, not for your ego.

Use a or the instead:

No The writer must keep his audience in mind.
Yes The writer must keep the audience in mind.

Rewrite the sentence or passage. In some cases, you can rephrase the sentence:

No Each user has his own login name and password.
No Each user has their own login name and password. (ambiguous).
Yes Each user has a personal login name and password.

Use a mixture of male and female names and scenarios in examples. You can then refer to John as he and Mary as she.

Titles

Many titles are gender-neutral (engineer, programmer, assistant, manager). But some times, you may have to find a gender-neutral alternative (for example, “sales rep” instead of “salesman”).

Stressing what is important in a sentence

Writing should be direct, clear, and concise. For example, you can change sentences containing it is, there is, or there are by more direct versions, as those phrases distract the reader from the important part of the message.

Examples

No There is a fee of $150 for this course.
Yes The fee for this course is $150.
No There are navigation buttons at the top of the screen.
Yes Navigation buttons are at the top of the screen.
Yes Use the navigation buttons at the top of the screen.
No There are three options for inserting an image . . .
Yes The options for inserting an image are . . .

You get the idea. These examples were not difficult to change, but some other uses of there is, there are, and it is are more complicated to fix; changes usually involve rewriting more than the sentence in which they appear.

Tips for reviewers

Here is a checklist of things to do when reviewing or editing a chapter for the user guides.

Record your changes

Be sure to record your changes when reviewing or editing a document. The author can then easily see what you’ve changed,and can accept or reject your changes.

To record changes, click Edit > Changes > Record. (You may also wish to use Edit > Changes > Show, but be aware that showing changes is likely to cause changes in page breaks.)

Use comments to leave notes

If you have a comments about a paragraph or section, rather than specific changes, avoid putting your notes directly into the text of the document. Use the “comments” feature: click Insert > Comment, and type your comments in the text box. Your initials and a timestamp are added automatically to your comments. Multiple reviewers can reply to your comments.

Separate different kinds of reviewing

Don’t try to fix everything on one pass. Make several passes, and on each pass check for something different.

  • Avoid copy-editing or substantive editing as you are reviewing the content; it slows you down and distracts you.
  • Avoid copy-editing or content reviewing as you are doing substantive editing; it slows you down and distracts you.
  • Avoid substantive editing or content reviewing as you are doing copy-editing; it slows you down and distracts you.
  • You can make separate passes for different aspects of copy-editing, such as grammar on one pass and punctuation on another pass.

Some people prefer to check for simple things first (like punctuation and use of styles) so that those things won’t distract them when they are doing substantive editing. Others prefer to do substantive editing first, so that they don’t spend time copy-editing things that they later delete or rewrite. Choose a strategy that works for you.

Other tips

  • Edit in small doses, and take frequent breaks. Divide the task into manageable chunks. Don’t edit for more than one hour at a time without taking a break.
  • Try to read for content only once; skim when looking for other problems on other passes.
  • Look for symbols that come in pairs – parentheses, brackets, and quotation marks for example. Writers often leave out the second mark in a pair.
  • Read the copy out of sequence, or backward. Consider reading paragraphs or pages out of order. Reading backward helps you focus on each word as a group of letters instead of as part of a meaningful phrase.

Tips for authors

Here are some suggestions to help you with writing a document.

  • Start writing where ever is easiest for you to start. You don’t have to start writing at the beginning and go in sequence to the end.
  • Some people like to create an outline first, but others like to write a bunch of text, and organize it later. Do whichever works best for you. However, creating an outline at some point in the writing process is a good idea. It can help you make sure you’ve covered all the topics you want to cover.
  • Leave the introduction for last, when you’re sure of everything that the rest of the document says.
  • Don’t worry if English is not your first language. Reviewers can help you refine the usage, grammar, and spelling (as well as the other aspects). This is true for native speakers, too.
  • Keep the typical user foremost in your mind. What’s obvious to you may not be obvious to someone with less experience with the product. Read the users@libreoffice.org mailing list to be aware of the types of problems users typically have.
  • To become a better writer, read a lot. (Listening to audio books counts.) Michael Bremer, author of Untechnical Writing, suggests reading not only technical books, but also popular science books, and even screenplays and good children’s books.

Resources

The following are some books and websites that may be useful or interesting for authors and editors.

English language references

OneLook Dictionary Search, http://www.onelook.com/. Searches multiple online dictionaries for a word or phrase.

University of Chicago, The Chicago Manual of Style Q & A, http://www.chicagomanualofstyle.org. Answers to questions on a great many matters of form, from Abbreviations to Word Division.

Technical writing and editing

You don’t have to fill your bookshelf with technical writing books in order to contribute to LibreOffice user guides. But if you’re interested, here are some resources that may be helpful.

Beer, David F. and David McMurrey. A Guide to Writing as an Engineer. Wiley, 1996. ISBN 0471117153. Targetted at helping “techies” communicate more clearly.

Bremer, Michael. Untechnical Writing: How to Write About Technical Subjects and Products So Anyone Can Understand. UnTechnical Press, 1999. ISBN 0966994906. A guide to the practical aspects of writing software documentation.

Perry, Carol Rosenblum, The Fine Art of Technical Writing. Blue Heron Publishing, 1991. ISBN 093608524X. Concise overview of technical writing.

Weber, Jean Hollis, The Technical Editors’ Eyrie, <http://www.jeanweber.com/>. Resources for technical editors.

Writing in general

Strunk, William Jr. and E.B. White, The Elements of Style, 4th ed. Longman, 2000. ISBN 020530902X. A “classic” that ranges over punctuation, usage, style, and composition in about 100 concise pages. The original edition, without White’s additions, is available online at http://www.bartleby.com/141/.

Williams, Joseph, Style: The Basics of Clarity and Grace. Longman, 2002. ISBN 0321112520 . Strunk and White tell you to “omit needless words.” Williams tells you how to figure out which words are needless. There are two other versions, Style: Ten Lessons in Clarity and Grace, and Style: Toward Clarity and Grace, which have more detailed discussion of the same principles. Ten Lessons is a textbook with very helpful exercises, while Toward is aimed at a general audience.

Preferred terminology

Term Preferred Over Usage Example
dialog(s) dialog box(es) In the xxx dialog, select yyy...
menu bar main menu From the menu bar, select xxx yyy zzz.
context menu contextual menu, any version of pop-up. any version of window Right-click and select xxx on the context menu.
page [of tabbed dialog] tab [for the operational area], any version of window
On the xxx page of the yyy dialog, …
[but]
Select the xxx tab and set..
[Needs confirmation – grep technique probably not applicable].
section subsection
Named portion of a dialog
[Needs confirmation – grep technique probably not applicable].