Style Guide

    From The Document Foundation Wiki
    This page contains changes which are not marked for translation.

    TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate

    Other languages:
    Documentation Contributors’ Guide
    Chapter 4 Style Guide for Writing User Guides
    Previous: Chapter 3 Up: Preface Next: Chapter 5

    Introduction

    Follow this guide when writing or editing chapters for the User Guides for LibreOffice 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

    Design information (what chapters should look like, including an explanation of when to use each style for paragraphs, characters, pages, frames, and numbering) is located in the LibreOffice Chapter Template, the LibreOffice Book Template, and Chapter 5 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, reviewers, and editors below.

    • Use short, simple, easy-to-understand words and sentences. Be concise and clear. Ideally:
      • Paragraphs should be no more the six sentences long.
      • Sentences should only contain a maximum of 20 words, with the occasional sentence up to 25 words.
    • Write in active voice or the imperative, using passive voice only when necessary or appropriate. For example, Do this, then do that. 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 is displayed.
    • Use the present tense, using future tense only when necessary or appropriate. Try to make your descriptions timeless. For example, write The File dialog is displayed, rather than The File dialog 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 the third person, for example phrase the user. Use second person (you) or the imperative.
    • 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. 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.
    • Avoid using the possessive apostrophe (for example Peter’s). Rewrite the sentence to remove the need for a possessive apostrophe.
    • Do not use contractions of words (for example: don’t becomes do not; won’t becomes will not, and so on).

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

    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/19 mean March 12, 2019 or 3 December 2019? Always spell out part or all of the month. Use formats like December 3, 2019 or 3 Dec 19.

    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.

    AutoCorrect backup (adj. or n.) back up (v.) bitmap checkbox
    database Menu bar disk drop down (v.) drop-down (adj.; do not use as a noun)
    email file name website hard disk hardware
    toolbar subdocument source code 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


    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, type the word “Figure” or “Table” and insert the number as a cross reference, choosing “Numbering” as the reference type.

    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 Keystroke 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, with no space before or after the + sign. If the combination requires a command key and a letter key, place the command key first. Example: Control+K.

    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 Strong Emphasis 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 click an icon or use a key combination, you can include that information.

    Do not try to include every way to perform an action every time you describe that action.

    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: You can conclude a step with "and press OK" or “and press Enter”.

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

    Include screenshots or other images when they help explain a step. Crop screenshots to emphasize the important part and remove distractions.

    Tips, Notes, and Cautions

    A Tip describes practical but nonessential information that does not otherwise fit into the flow of the text, for example 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.

    Try to limit the number of Tips, Notes, and Cautions to no more than two on a page. If necessary, reorganize the text to reduce their number.

    Use appropriate paragraph styles (Heading Tip, Heading Note, Heading Caution) and (for the text) Text Note.

    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.

    You can take screen captures from any operating system.

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

    On operating systems (such as macOS) where LibreOffice offers a choices between using the LibreOffice dialogs or the operating system-specific ones, select Use LibreOffice dialogs. This setting is found in Tools > Options > LibreOffice > General (on macOS, LibreOffice > Preferences > LibreOffice > General) 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 choices

    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 and code listings.
      • 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 (Emphasis 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? Do the terms used in the document match those used in the application?
    • 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 (sentences, paragraphs) 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 “checked out”. This means that the author is working on it. When the document is ready for review, the author uploads it to the Draft folder for that book. 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 “checked out”. This means that the author is working on it.
    2. When the document is ready for review, the author uploads it to the Draft folder for that book.
    3. The reviewer 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.
    • You can use they as a singular pronoun, but it is best to reword the sentence. Although major style guides now accept this usage, some people still regard it 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).

    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 > Track Changes > Record. (You may also wish to use Edit > Track 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, do not 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; it slows you down and distracts you. Make several passes, and on each pass check for something different: content, logic, language. You may also wish to 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 lot 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.
    Retrieved from "https://wiki.documentfoundation.org/index.php?title=Documentation/DocumentationTeamInfo/StyleGuide&oldid=765141"