Documentation/Dashboard/Help Style Guide

From Apache OpenOffice Wiki
Jump to: navigation, search

How-tos (Help guides)

Effective Document Structure

Providing Structural Elements

Readers are goal oriented and scan for information. Scannable documents help readers to locate information quickly. To structure your documents accordingly, do the following:

  • Write meaningful headings and subheadings.
    Headings and subheadings should be short, precise abstracts of the associated content because they are often displayed out of context and may be truncated in search results lists.
    Do not go beyond fourth-level headings and try to have at least two headings at each level.
    Avoid meaningless headings such as "Overview" or "Introduction".
    Try to use parallel construction (for example, gerunds) when writing headings at the same level.
  • Keep paragraphs short.
    To emphasize main points limit each paragraph to one idea and do not write more than three to five sentences per paragraph (or a maximum of 75 words).
  • Use bulleted and numbered lists.
    Bulleted and numbered lists help to break up hard-to-read screen text and provide white space that gives the eyes a visual break. Therefore, use more lists online than you would on a typical printed page.
    Avoid having more than nine items in a list. If that is not possible try to divide the list into two or more lists.
    Lists must include at least two items.
    Use numbered lists when the entries are dependent on the sequence in which you present them (for example a step-by-step procedure). Use bulleted lists when the entries are not dependent on sequence (for example action alternatives).
  • Replace text with tables and figures, when possible.
    Make tables short and simple to improve online readability and reduce load time. Consider using a table instead of a bulleted list for long lists with repeating elements.

Writing Short Self-Contained Topics

These guidelines help readers find needed information quickly:

  • Create self-contained topics and link them to other topics.
    Make each topic clearly focused and coherent so that it answers one question about one subject for one purpose.
    If necessary, repeat contextual information within each topic to help orient readers so that they know what the current topic is and how it fits within the larger document structure.
    Links to overviews or similar explanatory information can help readers who need more background.
  • Include transitions within each topic.
    Use transitions between and within paragraphs to show how ideas relate to each other. But do not repeat the heading content in introductory sentences.

Preserving Context

Online readers jump around through traversing links choosing their own path through the documentation. To preserve context follow these guidelines:

  • Offer contextual cues.
    Help readers understand where the information belongs within the larger structure of the document. For example, you could indicate to readers that a certain topic is part of a broader topic or offer them a link to it.
  • Make assumptions about reading order.
    You usually do not know how readers come to your document. They might arrive through a table of contents or a search machine. Or they clicked a link that lead them there. When you make few assumptions here, you are better prepared to offer readers the necessary contextual cues.

Using Links

Links are one of the advantages of online reading because they enable readers to go their own way through the documentation. However, links pose challenges for writers: Too many links clutter text, can distract readers and may involve a lot of maintenance. Too few links make it difficult for readers to find supplemental information.

  • Write jump lists.
    A jump list is a bulleted list of links that may serve as a kind of table of contents for a longer topic or as a list of related topics.
    Place the table-of-contents jump list at the beginning of your topic to allow the reader to select specific subtopics right from the start. This is particularly useful for long topics like Calc function lists.
    The related-topics jump list is better placed at the end of a topic, so that the reader can decide, after having read the topic, if further information is needed.
  • Embed links in text.
    Provide readers with opportunities but do not exaggerate. To reduce the amount of information that users see, briefly summarize content and then link to supporting details. For example, you can link to long examples, overviews, background, reference, detailed or supplementary information.
    If you create links to external web sites, make sure that they are relatively stable and not subject to frequent changes.
    When readers must follow a step-by-step procedure through your content, limit their choices by avoiding embedded links.
  • Avoid overlinking.
    Identifying a link once per topic is sufficient.
    Avoid internal linking that takes readers only a few lines down. Readers typically expect links to take them to another page.
  • Use links to make text seem shorter.
    Before starting to write search for similar topics and link to, rather than duplicate, information.
    Link to basic information, if possible. So expert users do not stop reading.
  • Guidelines for crafting link text
    • Weave link text into sentence structure:
      Make the text of the link meaningful and part of the natural syntax of the sentence.
      Avoid "click here" or "go here" links.
    • Make the link text short but informative:
      Think of links as emphasized words. One to three context-rich words works best for one link.
    • Write scannable link text:
      Write links as though your reader were scanning only the links on the page. Make them self-explanatory and scannable.
    • Make link text conceptually similar to titles or headings:
      The link text should be conceptually similar to the title or heading of the associated link destination.
      Also, use consistent wording for link text that leads to the same link destination.

Formats

Headings

  • Follow American English capitalization guidelines for headings.
    Capitalize the first letter of every word except conjunctions, articles, prepositions of fewer than four letters, and the "to" in infinitives.
  • Use parallel construction for headings at the same level.
    Headings on the first level, for example, generally use a gerund like "Installing", subheadings typically begin with "to" + infinitive as in "To Download Installation Files"
  • Do not number headings.
    As topics are short, numbering is not necessary.

Write Clearly and Simply

  • Use simple declarative and imperative sentence structures.
    For example: "To change the password, replace the current password"
    is better than "If you want to change the password, you can replace the current password."
  • Use active voice and present tense.
    Passive voice is ok in sentences like "The file dialog box is displayed" where the focus is on the receiver of an action and the "doer" (program) is obvious or not important.
  • Use terms consistently.
    Otherwise, readers have to recheck different topics to grasp the meaning of the material.

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 only for advanced users and are treated in special topics.
  • Number the procedure steps.
    If a procedure has two or more steps use numbered lists to describe the order of the steps.
  • 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".

Styles

Pictures

  • Use the PNG format for screenshots.
  • Avoid humour in screenshot content.
    Humour is culture dependent, and therefore you risk offending the audience.
  • Avoid icons.
    Whenever possible describe procedures as menu paths.

Date and Time Format

  • Write out dates.
    Dates are displayed differently in different countries. So, it is better to write "June 28, 2005" instead of "6/28/05". If abbreviations are necessary, use the order Year-Month-Day ("2005-06-28"), which is the ISO standard and also common in Asia.
  • Describe the time in relation to the time of day or use a 24-hour system.
    Times are also displayed differently in different countries. Therefore, use for example "1:00 in the afternoon" or "13:00" instead of "1:00 p.m."

Abbreviations and Acronyms

  • To introduce an acronym, spell out the full term, followed by the acronym in parentheses.
    For example, "OpenOffice.org (OOo)".
  • Avoid "i.e.", "e.g." and "etc."
    Instead use "that is", "for example" and try to be more explicit in enumerations.

Content

Consistent Use of GUI Elements

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

Testing

Finally, check the correctness of the described procedures by using the application:

  • Are any steps missing?
  • Do the described steps match what happens in the application?

Calc functions

A typical help text for a Calc function should follow this scheme of paragraph styles:

Style Function Example
hidden text Index entry <BOOKMARKVALUE>DATE function</BOOKMARKVALUE>
  • hlp_head2
  • 16p
  • bold
  • capital letters
Second level heading
DATE
hlp_paragraph Function description This function converts a date written as year, month, day to an internal serial number and displays it in the cell's formatting. The default format of a cell containing the DATE function is the date format, but you can format the cells with the 0 number format, which displays the internal serial number of the date as a number.
  • hlp_head3
  • 14p
  • bold
  • without colon
Third level heading
Syntax
  • hlp_code
  • no blank before and after parentheses
  • arguments are separated by semicolon and blank
  • arguments begin with a capital letter
  • arguments that consist of more than one word are contracted (ex.: DegreesFreedom)
  • mandatory quotes must be entered in the syntax code
Syntax definition DATE(Year; Month; Day)
  • hlp_paragraph
  • 10p
  • argument is bold without colon
Explanation of function arguments Year is an integer between 1583 and 9956 or 0 and 99. In Tools - Options - StarOffice - General you can set from which year a two-digit number entry is recognized as 20xx.
  • hlp_head3
  • 14p
  • bold
  • without colon
Third level heading
Example
  • hlp_paragraph
  • starting with an equal sign
  • character style hlp_input for example text and entries
  • without blanks
  • results are not bold
  • no quotes, except if they are literal
  • use the new character style hlp_input for data that have to be entered literally and for examples
Example =DATE(00;1;31) yields 1/31/00 if the cell format setting is MM/DD/YY.


Distribution of Function Descriptions in the Help (see also issue 71289)

  • One file for every Calc function: Every Calc function should be presented as a self-contained entity as we have it already for some functions like DATE, HOUR, YEAR and some others.
  • One function list for every function category (main_{categoryname}.xhp): The individual Calc functions should be bundled in a category file. These category files should contain a list of the related functions, each with a short description (that can be taken from the Calc function file) and a link to the corresponding Calc function file.
  • One list of categories (main_functions.xhp): Overview of all categories with links to the categories pages. Therefore it would be better to name it main_categories.xhp.

Checklist for the Completeness of Function Descriptions

Here are some hints related to the contents that should be considered in every function description although they are sometimes missing in the actual help files.

  • Think global when you give examples. The english documentation is an international one.
  • Give unambiguous examples.
  • Mention differences to Excel.
  • Advise of argument types that are silently converted.
  • Advise of general settings that influence the result.
  • Mention the mathematical formula, which is used to calculate the result.
  • Advise of incorrect arguments that generate no error.
  • Tell the user, if named ranges, named formulas, labels or named data ranges are not resolved to their content or are forbidden.
  • Tell the user if internal underflow or overflow is not automatically detected. Tell about the accuracy if possible.
Personal tools