Documentation/Dashboard/Help Style Guide

Help "Guides" (How-to instructions)

Current Style

A typical guide follows this scheme of paragraph styles:

Style	Function	Example
hlp_aux_bookmark	Index entry	<BOOKMARKVALUE>tables;calculating across</BOOKMARKVALUE>
hlp_head1	First level heading	Calculating Across Tables
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.
hlp_listitem	Step-by-step description	1. Open a text document, insert two tables, and type numbers in a few cells in both tables....
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

Several other paragraph styles can be inserted in this framework:

• 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

There are also character styles:

• hlp_acronym
• hlp_aux_comment
• hlp_aux_parachanged
• hlp_aux_tag
• hlp_emph
• hlp_keycode
• hlp_literal
• hlp_menuitem
• hlp_path

Style inconsistencies

Headings	Missing heading levels: After heading level 1 follows heading level 3. (ex.: draw guide groups.xhp). Missing headings. ex: in Writer guide hidden_text.xhp the first How to has no heading. In even_odd_sdw.xhp 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 guide form_letters_main.xhp, where hlp_head2 repeats the contents of hlp_head1, and no other hlp_head2 follows. Unformatted headings (ex.: in Calc guide table_view.xhp headings are formatted as simple hlp_paragraph). Inconsistent use of capitals in subheadings (compare Shared guide mobiledevicefilters.xhp to Calc guide cellstyle_conditional.xhp). In Math some how to headings are formulated in FAQ style.
Tables	Misuse of hlp_paragraph in table content. (ex. Writer guide fields_userdata.xhp).
Bullets	Different styles for bullet paragraphs (hlp_listitem and hlp_paragraph) produce inconsistent spacing between paragraphs. (ex.: Writer guide footnote_usage.xhp). Misuse of bullets (in Writer guide auto_spellcheck.xhp there is no logical connection between the bullet paragraphs. In other cases as Writer guide finding.xhp, there are single bullets without being in a list). Steps with bullets instead of numbers (ex.: shared guide pageformat_max.xhp). Missing bullets (ex.: In Calc guide cell_protect.xhp the options in steps 3 and 5 should have bullets).
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 guide conditional_text.xhp). Result formatted like a step (ex.: Calc guide cellreference_dragdrop.xhp). Step without number formatted as hlp_paragraph (ex.: shared guide spadmin.xhp). Numbered action alternatives, should be bullets (ex.: shared guide start_parameters.xhp). Numbered list of steps put into a table (ex.: shared guide redlining_enter.xhp).
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 guide csv_formula.xhp). Note in the "Related Topics" section (ex.: shared guide Autohide.xhp).
Related topics	Different styles in the "Related topics" link list: help_aux_embed and hlp_paragraph.
Character styles	Misuse of hlp_emph for menu items. Unformattet menu items (ex. View-toolbars-drawing in Calc guide keyboard.xhp), buttons (ex. OK in Calc guide design.xhp), icon names (ex.: shared guide edit_symbolbar.xhp) and toolbar names (ex.: link in shared guide insert_bitmap.xhp). Shortcut keys are sometimes bold (Calc guide keyboard.xhp) and sometimes not bold (Calc guide auto_off.xhp). "Navigator" sometimes is bold sometimes not (compare Writer guide arrange_chapters.xhp to shared guide navigator.xhp). Tabs normally are formatted in bold but not always ("Contents" tab in shared guide digital_signatures.xhp).
Order of styles	Normally, How to's are introduced by short feature descriptions. In Writer Guide finding.xhp, "Navigator" section, the order is inverted.
Broken semantic entities	Ex: in Writer Guide footnote_usage 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

• 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.
• Icons in bullet lists are disturbing the layout (see for example shared guide copytext2application.xhp)