Documentation/Dashboard/Help Style Guide

From Apache OpenOffice Wiki
< Documentation‎ | Dashboard
Revision as of 11:25, 8 October 2007 by Mwaller (Talk | contribs)

Jump to: navigation, search

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 index entry "groups;entering").
  • 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.
Tables Misuse of hlp_paragraph in table content. (ex. Writer index entry "fields;user data").
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).
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").
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").
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: 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").
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.
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

  • 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 index entry "text;copying by drag and drop")

Calc functions

The Calc functions are described in 22 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 issue 54559)

string "Syntax"
  • "Syntax" normally appears as Syntax, but in the mathematical functions you can find also Syntax:
string "Example"
  • "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:
Function syntax
  • Sometimes there is a space missing after the colon that separates the arguments.
  • Sometimes there is an unnecessary space before the opening bracket.
  • Sometimes argument names begin with capital, sometimes not.
Function arguments
  • Function arguments sometimes appear as <argument>: and sometimes as <argument>.

Dialog descriptions (reference files)

Personal tools