Documentation/Dashboard/Help Style Guide

How-tos (Help guides)

Effective Document Structure

Structuring Documents

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

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.