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

From Apache OpenOffice Wiki
Jump to: navigation, search
(Style inconsistencies (see also [http://www.openoffice.org/issues/show_bug.cgi?id=54559 issue 54559]))
(Headings: Added start with level 2 headings)
 
(118 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Help "Guides" (How-to instructions)==
+
==How Tos (Help guides)==
 +
This style guide focuses on How Tos in the Documentation Wiki.
  
===Current Style===
+
===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.''' <br> 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. <br> Do not go beyond fourth-level headings and try to have at least two headings at each level. <br> Avoid headings such as "Overview" or "Introduction". These belong in Guides, but not in How Tos.
 +
* '''Keep paragraphs short.''' <br> 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.''' <br> 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. <br> Avoid having more than nine items in a list. If that is not possible try to divide the list into two or more lists. <br> Lists must include at least two items. <br> 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.''' <br> 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.
  
A typical guide follows this scheme of paragraph styles:
+
====Writing Short Self-Contained Topics====
 +
These guidelines help readers find needed information quickly:
 +
* '''Create self-contained topics and link them to other topics.''' <br> Make each topic clearly focused and coherent so that it answers one question about one subject for one purpose. <br> 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. <br> Links to overviews or similar explanatory information can help readers who need more background.
 +
* '''Include transitions within each topic.''' <br> Use transitions between and within paragraphs to show how ideas relate to each other. But do not repeat the heading content in introductory sentences.
  
{| cellpadding="3" cellspacing="1" style="background-color: #666; margin-left: 3em;"
+
====Preserving Context====
|- bgcolor="#DDD"
+
Online readers jump around through traversing links, choosing their own path through the documentation. To preserve context, follow these guidelines:
! Style !! Function !! Example
+
* '''Offer contextual cues.''' <br> 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.
|- bgcolor="#FFF"
+
* '''Make few assumptions about reading order.''' <br> 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.
| hlp_aux_bookmark||Index entry|| <BOOKMARKVALUE>tables;calculating across</BOOKMARKVALUE>
+
|- bgcolor="#FFF"
+
| hlp_head1||First level heading|| '''Calculating Across Tables'''
+
|- bgcolor="#FFF"
+
| hlp_paragraph||Introductory feature description, often beginning with "You can..."|| You can perform calculations that span across more than one table in a text document.
+
|- bgcolor="#FFF"
+
| hlp_listitem||Step-by-step description|| 1. Open a text document, insert two tables, and type numbers in a few cells in both tables....  
+
|- bgcolor="#FFF"
+
| hlp_aux_embed||"Related Topics" section with links to other help files || <EMBED href="text/shared/00/00000004.xhp#related">
+
|}
+
  
hlp_aux styles = Styles that are created automatically when you insert a text element by the help authoring menu
+
====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.
  
Several other paragraph styles can be inserted in this framework:
+
* '''Write jump lists.''' <br> 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. <br> 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. <br> 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.
* hlp_tablehead and hlp_tablecontent for tables
+
* hlp_tip, hlp_note and hlp_warning for tips, notes and warnings
+
* hlp_head2,..., hlp_head5 for further heading levels
+
* hlp_example
+
* hlp_code for code snippets (variables for ex.)
+
* hlp_default
+
* hlp_head
+
  
 +
* '''Embed links in text.''' <br> 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. <br> If you create links to external web sites, make sure that they are relatively stable and not subject to frequent changes. <br> When readers must follow a step-by-step procedure through your content, limit their choices by avoiding embedded links.
  
There are also character styles:
+
* '''Avoid overlinking.''' <br> Identifying a link once per topic is sufficient. <br> Avoid internal linking that takes readers only a few lines down. Readers typically expect links to take them to another page.
* hlp_acronym
+
* hlp_aux_comment
+
* hlp_aux_parachanged
+
* hlp_aux_tag
+
* hlp_emph
+
* hlp_keycode
+
* hlp_literal
+
* hlp_menuitem
+
* hlp_path
+
  
===Style inconsistencies===
+
* '''Use links to make text seem shorter.''' <br> Before starting to write, search for similar topics and link to, rather than duplicate, information. <br> Link to basic information, if possible, so expert users do not stop reading.
  
{| cellpadding="5" cellspacing="1" style="background-color: #666; margin-left: 3em;"
+
* '''Guidelines for crafting link text'''
|- bgcolor="#FFF"
+
**'''Weave link text into sentence structure:''' <br> Make the text of the link meaningful and part of the natural syntax of the sentence. <br> Avoid "click here" or "go here" links.
! Headings
+
** '''Make the link text short but informative:''' <br> Think of links as emphasized words. One to three context-rich words works best for one link.
|
+
** '''Write scannable link text:''' <br> Write links as though your reader were scanning only the links on the page. Make them self-explanatory and scannable.
* Missing heading levels: After heading level 1 follows heading level 3. (ex.: Draw index entry "groups;entering").
+
** '''Make link text conceptually similar to titles or headings:''' <br> The link text should be conceptually similar to the title or heading of the associated link destination. <br> Also, use consistent wording for link text that leads to the same link destination.
* Missing headings. (ex: Writer index entry "text;hiding": the first How to has no heading.)
+
* Writer index entry "right pages": hlp_head2 is not defined correctly.
+
* Heading sub-levels (To do...) sometimes have colons.
+
* Inconsistent wording in headings: To do..., -ing form, imperative, noun.
+
* Unnecessary headings, ex.: Writer index entry "form letters": hlp_head2 repeats the contents of hlp_head1, and no other hlp_head2 follows.
+
* Unformatted headings (ex.: Calc index entry "tables;view": headings are formatted as simple hlp_paragraph).
+
* Inconsistent use of capitals in subheadings (compare Shared index entry "mobile device filters" to Calc index entry "formats;conditional").
+
* In Math some How To headings are formulated in FAQ style.
+
|- bgcolor="#FFF"
+
! Tables
+
| Misuse of hlp_paragraph in table content. (ex. Writer index entry "fields;user data").
+
|- bgcolor="#FFF"
+
! Bullets
+
|
+
* Different styles for bullet paragraphs (hlp_listitem and hlp_paragraph) produce inconsistent spacing between paragraphs. (ex.: Writer index entry "deleting;footnotes").
+
* Misuse of bullets (ex.: Writer index entry "automatic spellcheck": there is no logical connection between the bullet paragraphs. In other cases as Writer index entry "styles;finding", there are single bullets without being in a list).
+
* Steps with bullets instead of numbers (ex.: shared index entry "page formats;maximizing").
+
* Missing bullets (ex.: Calc index entry "cells;protecting": the options in steps 3 and 5 should have bullets).
+
|- bgcolor="#FFF"
+
! Numbered lists
+
|
+
* Text referring to a list item is formatted as hlp_paragraph instead of hlp_listitem. The connection to the list item is not visible. (ex.: Writer index entry "defining;conditions").
+
* Result formatted like a step (ex.: Calc index entry "cells;referencing by drag and drop").
+
* Step without number formatted as hlp_paragraph (ex.: shared index entry "spadmin").
+
* Numbered action alternatives, should be bullets (ex.: shared index entry "start parameters").
+
* Numbered list of steps put into a table (ex.: shared index entry "changes;recording").
+
|- bgcolor="#FFF"
+
! Tips, notes and warnings
+
|
+
* There is no obvious difference between the use of tips and notes. Often I cannot see any distinction to normal paragraph text either.
+
* Missing warning symbol (ex.: Calc index entry "csv files;spreadsheets").
+
* Note in the "Related Topics" section (ex.: shared index entry "docking;windows").
+
|- bgcolor="#FFF"
+
! Related topics
+
|Different styles in the "Related topics" link list: help_aux_embed and hlp_paragraph.
+
|- bgcolor="#FFF"
+
! Character styles
+
|
+
* Misuse of hlp_emph for menu items.
+
* Unformattet menu items (ex. View-toolbars-drawing: Calc index entry "accessibility; StarOffice Calc shortcuts"), buttons (ex. OK: Calc index entry "layout;spreadsheets), icon names (ex.: shared index entry "buttons;toolbars") and toolbar names (ex.: link in shared index entry "aging filter").
+
* Shortcut keys are sometimes bold (Calc index entry "accessibility; StarOffice Calc shortcuts") and sometimes not bold (Calc index entry "text completion on/off").
+
* "Navigator" sometimes is bold sometimes not (compare Writer index entry "moving;headings" to shared index entry "Navigator;contents as lists").
+
* Tabs normally are formatted in bold but not always ("Contents" tab: shared index entry "certificates").
+
|- bgcolor="#FFF"
+
! Order of styles
+
|Normally, How to's are introduced by short feature descriptions. But enter Writer index entry "styles;finding": in the "Navigator" section, the order is inverted.
+
|- bgcolor="#FFF"
+
! Broken semantic entities
+
|Ex: Writer index entry "deleting;footnotes": the sentence with the hand symbol semantically belongs to the bullet point above. But this is not visible in the layout. This sentence should be indented.
+
|}
+
  
===Bad Style===
+
===Formats===
 +
Apart from [[Documentation/Dashboard/Styles|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.''' <br> 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.''' <br> 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.''' <br> As topics are short, numbering is not necessary.
 +
* ''' Start with Level 2 headings.''' <br> Level 1 headings should be reserved for page title.
  
* Bullets (action alternatives) under Numbering (steps in To Do's) look ugly. They should be more indented, so that the bullet is directly under the first letter of the numbered paragraph above. But bullet text that does not refer to a preceding numbered paragraph should not be indented.
+
====Write Clearly and Simply====
* Icons in bullet lists are disturbing the layout (see for example shared index entry "text;copying by drag and drop")
+
*'''Use simple declarative and imperative sentence structures.''' <br> For example: "To change the password, replace the current password" <br> is better than "If you want to change the password, you can replace the current password."
 +
*'''Use active voice and present tense.''' <br> 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.''' <br> Otherwise, readers have to recheck different topics to grasp the meaning of the material.
  
 +
====Lists====
 +
*'''Finish a list introduction with the proper punctuation mark.''' <br> Use a colon at the end of a list introduction if the introduction contains phrasing as "the following" or "as follows". <br> 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.'''
  
==Calc functions==
+
====Procedure Descriptions====
 +
*'''To describe single procedures use menu items''' <br> 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.''' <br> 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''' <br> 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.''' <br> Tell readers what is to happen after a step, in a separate line under the step text.
  
===Current Style===
+
====Notes, Tips, and Cautions====
 +
Use a '''Note''' to break out related, reinforcing or other special information, for example an explanation or comment.
  
A typical help text for a Calc function follows this scheme of paragraph styles:
+
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.
  
{| cellpadding="3" cellspacing="1" style="background-color: #666; margin-left: 3em;"
+
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.
|- bgcolor="#DDD"
+
 
 +
* '''Keep the text of Notes, Tips and Cautions short and relevant.''' <br> 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.''' <br>If necessary, reorganize the text to reduce their number.
 +
 
 +
====Pictures====
 +
* '''Use the PNG format for screenshots.'''
 +
* '''Avoid humour in screenshot content.''' <br> Humour is culture dependent, and therefore you risk offending the audience.
 +
* '''Avoid icons.''' <br> Whenever possible describe procedures as menu paths.
 +
 
 +
====Date and Time Format====
 +
*'''Write out dates.''' <br> 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.''' <br> 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.''' <br> For example, "OpenOffice.org (OOo)".
 +
*'''Avoid first usage of an acronym/abbreviation in a chapter title, heading, or caption.''' <br> 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."''' <br> Instead use "that is", "for example" and try to be more explicit in enumerations.
 +
 
 +
====[[Documentation/Dashboard/Styles|Styles]]====
 +
The [[Documentation/Dashboard/Styles|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:
 +
 
 +
{| cellpadding="3" cellspacing="1" style="background-color: #666666; margin-left: 3em;"  
 +
|- bgcolor="#DDDDDD"
 
! Style !! Function !! Example  
 
! Style !! Function !! Example  
|- bgcolor="#FFF"
+
|- bgcolor="#FFFFFF"
| hlp_aux_bookmark||Index entry|| <BOOKMARKVALUE>ISFORMULA function</BOOKMARKVALUE>
+
| hidden text||Index entry|| <BOOKMARKVALUE>DATE function</BOOKMARKVALUE>
|- bgcolor="#FFF"
+
|- bgcolor="#FFFFFF"
| hlp_head2||Second level heading|| '''ISFORMULA'''
+
||
|- bgcolor="#FFF"
+
* hlp_head2
| hlp_paragraph||Feature description || Returns TRUE if a cell is a formula cell.
+
* 16p
|- bgcolor="#FFF"
+
* bold
| hlp_head3||Third level heading|| '''Syntax'''
+
* capital letters
|- bgcolor="#FFF"
+
||Second level heading|| <div style=" font-weight: bold; font-size: 140%; "> DATE </div>
| hlp_code||Syntax code || ISFORMULA(reference)  
+
|- bgcolor="#FFFFFF"
|- bgcolor="#FFF"
+
| 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_paragraph||Explanation of function arguments || '''Reference''' indicates the reference to a cell in which a test will be performed to determine if it contains a formula.
+
|- bgcolor="#FFFFFF"
|- bgcolor="#FFF"
+
||
| hlp_head3||Third level heading|| '''Example'''
+
* hlp_head3
|- bgcolor="#FFF"
+
* 14p
| hlp_paragraph||Example || ISFORMULA(C4) returns FALSE if the cell C4 contains the number 5.
+
* bold
 +
* without colon
 +
||Third level heading|| <div style=" font-weight: bold; font-size: 130%; "> Syntax </div>
 +
|- bgcolor="#FFFFFF"
 +
||
 +
* 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)  
 +
|- bgcolor="#FFFFFF"
 +
||
 +
* 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.
 +
|- bgcolor="#FFFFFF"
 +
||
 +
* hlp_head3
 +
* 14p
 +
* bold
 +
*without colon
 +
||Third level heading|| <div style=" font-weight: bold; font-size: 130%; "> Example </div>
 +
|- bgcolor="#FFFFFF"
 +
||
 +
* 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 || <I> =DATE(00;1;31) </I> yields 1/31/00 if the cell format setting is MM/DD/YY.
 
|}
 
|}
  
Most of the Calc functions are described in the files from text/scalc/01/04060101.xhp up to text/scalc/01/04060185.xhp. In the Calc Help they can be found under the index entry "Calc functions".
 
  
===Style inconsistencies (see also [http://www.openoffice.org/issues/show_bug.cgi?id=54559 issue 54559])===
 
  
{| cellpadding="5" cellspacing="1" style="background-color: #666; margin-left: 3em;"
+
===Distribution of Function Descriptions in the Help (see also {{Bug|71289}})===
|- bgcolor="#FFF"
+
* '''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.
! string "Syntax"
+
* '''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'''.
* "Syntax" normally appears as '''Syntax''', but in the mathematical functions you can find also '''Syntax:'''
+
 
|- bgcolor="#FFF"
+
===Checklist for the Completeness of Function Descriptions===
! string "Example"
+
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.
* "Example" normally appears as '''Example''' but in the mathematical functions and in some individual cases in Analysis functions (Part 2) and spreadsheet functions you can find also '''Example:'''
+
* Give unambiguous examples.
|- bgcolor="#FFF"
+
* Mention differences to Excel.
! Function syntax
+
* Advise of argument types that are silently converted.
|
+
* Advise of general settings that influence the result.
* Sometimes there is a space after the colon that separates the arguments, sometimes not.
+
* Mention the mathematical formula, which is used to calculate the result.
* Sometimes there is an unnecessary space before or after the opening bracket.
+
* Advise of incorrect arguments that generate no error.
* Sometimes argument names begin with capital, sometimes not.
+
* Tell the user, if named ranges, named formulas, labels or named data ranges are not resolved to their content or are forbidden.
|- bgcolor="#FFF"
+
* Tell the user if internal underflow or overflow is not automatically detected. Tell about the accuracy if possible.
! Function arguments
+
 
|
+
{{PDL1}}
* Function arguments sometimes appear as <argument>: and sometimes as <'''argument'''>.
+
|- bgcolor="#FFF"
+
! Heading levels
+
|
+
* Most of the functions are heading level 2 because they are grouped in lists (for ex. index entry "Information functions"). But some functions (for ex. index entry "DATE function") got a single file and are therefore heading level 1.
+
|}
+
  
==Dialog descriptions (reference files)==
+
[[Category:Guidelines]]
 +
[[Category:How to]]
 +
[[Category:Documentation/Dashboard]]

Latest revision as of 08:13, 23 March 2013

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, "OpenOffice.org (OOo)".
  • 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:

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.
Content on this page is licensed under the Public Documentation License (PDL).
Personal tools