Difference between revisions of "Documentation/Dashboard/Help Style Guide"

Latest revision as of 11:48, 21 July 2022

How Tos (Help guides)

This style guide focuses on How Tos in the Documentation Wiki.

Effective Document Structure

The guidelines in this section are particularly important for writing online documents.

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. For the same reason you should place the most important words first, and avoid starting headings with an article.
  Do not go beyond fourth-level headings and try to have at least two headings at each level.
  Avoid headings such as "Overview" or "Introduction". These belong in Guides, but not in How Tos.
• 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). Use running text for up to four one-word items that have equal weight and no order.
• 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 few 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 led 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 See-Also 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

Apart from Styles the guidelines in this section are useful for every type of documentation not only for online documentation.

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.
• Start with Level 2 headings.
  Level 1 headings should be reserved for page title.

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.

Lists

• Finish a list introduction with the proper punctuation mark.
  Use a colon at the end of a list introduction if the introduction contains phrasing as "the following" or "as follows".
  If the introduction is complete in itself, use a period. For example: "There are three ways to send a mail message."
• Guidelines for constructing list items:
  • Capitalize the first word of each list item except for placeholders and other literal computer terms.
  • 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.

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.
  If a procedure has two or more steps use numbered lists to describe the order of the 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, in a separate line under the step text.

Notes, Tips, and Cautions

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

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.

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 Notes, Tips 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.

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/abbreviation, spell out the full term, followed by the acronym/abbreviation in parentheses.
  For example, "Apache OpenOffice (AOO)".
• Avoid first usage of an acronym/abbreviation in a chapter title, heading, or caption.
  If it is unavoidable, use either the full term or the acronym/abbreviation depending on which item is more familiar to your audience. Then, provide the missing information in the paragraph immediately following the chapter title, heading, or caption.
• Avoid "i.e.", "e.g." and "etc."
  Instead use "that is", "for example" and try to be more explicit in enumerations.

Styles

The Styles page contains a table with templates for character and paragraph styles that may help you when formatting a Wiki help topic.

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:

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.