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

From Apache OpenOffice Wiki
Jump to: navigation, search
 
(→‎Style inconsistencies)
Line 51: Line 51:
 
! Headings
 
! Headings
 
|
 
|
−
* Missing heading levels: After heading level 1 follows heading level 3. (ex.: draw guide groups.xhp).
+
* Missing heading levels: After heading level 1 follows heading level 3. (ex.: Draw index entry "groups;entering").
−
* Missing headings. ex: in Writer guide hidden_text.xhp the first How to has no heading.
+
* Missing headings. (ex: Writer index entry "text;hiding": the first How to has no heading.)
−
* In even_odd_sdw.xhp hlp_head2 is not defined correctly.
+
* Writer index entry "right pages": hlp_head2 is not defined correctly.
 
* Heading sub-levels (To do...) sometimes have colons.
 
* Heading sub-levels (To do...) sometimes have colons.
 
* Inconsistent wording in headings: To do..., -ing form, imperative, noun.
 
* 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.
+
* 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.: in Calc guide table_view.xhp headings are formatted as simple hlp_paragraph).
+
* Unformatted headings (ex.: Calc index entry "tables;view": headings are formatted as simple hlp_paragraph).
−
* Inconsistent use of capitals in subheadings (compare Shared guide mobiledevicefilters.xhp to Calc guide cellstyle_conditional.xhp).
+
* 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.
+
* In Math some How To headings are formulated in FAQ style.
 
|- bgcolor="#FFF"
 
|- bgcolor="#FFF"
 
! Tables
 
! Tables
−
| Misuse of hlp_paragraph in table content. (ex. Writer guide fields_userdata.xhp).
+
| Misuse of hlp_paragraph in table content. (ex. Writer index entry "fields;user data").
 
|- bgcolor="#FFF"
 
|- bgcolor="#FFF"
 
! Bullets
 
! Bullets
 
|  
 
|  
−
* Different styles for bullet paragraphs (hlp_listitem and hlp_paragraph) produce inconsistent spacing between paragraphs. (ex.: Writer guide footnote_usage.xhp).
+
* Different styles for bullet paragraphs (hlp_listitem and hlp_paragraph) produce inconsistent spacing between paragraphs. (ex.: Writer index entry "deleting;footnotes").
−
* 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).
+
* 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 guide pageformat_max.xhp).
+
* Steps with bullets instead of numbers (ex.: shared index entry "page formats;maximizing").
−
* Missing bullets (ex.: In Calc guide cell_protect.xhp the options in steps 3 and 5 should have bullets).
+
* Missing bullets (ex.: Calc index entry "cells;protecting": the options in steps 3 and 5 should have bullets).
 
|- bgcolor="#FFF"
 
|- bgcolor="#FFF"
 
! Numbered lists
 
! 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).
+
* 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 guide cellreference_dragdrop.xhp).
+
* Result formatted like a step (ex.: Calc index entry "cells;referencing by drag and drop").
−
* Step without number formatted as hlp_paragraph (ex.: shared guide spadmin.xhp).
+
* Step without number formatted as hlp_paragraph (ex.: shared index entry "spadmin").
−
* Numbered action alternatives, should be bullets (ex.: shared guide start_parameters.xhp).
+
* Numbered action alternatives, should be bullets (ex.: shared index entry "start parameters").
−
* Numbered list of steps put into a table (ex.: shared guide redlining_enter.xhp).
+
* Numbered list of steps put into a table (ex.: shared index entry "changes;recording").
 
|- bgcolor="#FFF"
 
|- bgcolor="#FFF"
 
! Tips, notes and warnings
 
! 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.
 
* 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).
+
* Missing warning symbol (ex.: Calc index entry "csv files;spreadsheets").
−
* Note in the "Related Topics" section (ex.: shared guide Autohide.xhp).
+
* Note in the "Related Topics" section (ex.: shared index entry "docking;windows").
 
|- bgcolor="#FFF"
 
|- bgcolor="#FFF"
 
! Related topics
 
! Related topics
Line 91: Line 91:
 
|
 
|
 
* Misuse of hlp_emph for menu items.
 
* 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).
+
* 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 guide keyboard.xhp) and sometimes not bold (Calc guide auto_off.xhp).
+
* 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 guide arrange_chapters.xhp to shared guide navigator.xhp).
+
* "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 in shared guide digital_signatures.xhp).
+
* Tabs normally are formatted in bold but not always ("Contents" tab: shared index entry "certificates").
 
|- bgcolor="#FFF"
 
|- bgcolor="#FFF"
 
! Order of styles
 
! Order of styles
−
|Normally, How to's are introduced by short feature descriptions. In Writer Guide finding.xhp, "Navigator" section, the order is inverted.
+
|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"
 
|- bgcolor="#FFF"
 
! Broken semantic entities
 
! 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.
+
|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.
 
|}
 
|}
  

Revision as of 12:06, 2 October 2007

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 guide copytext2application.xhp)

Calc functions

Dialog descriptions (reference files)

Retrieved from "https://wiki.openoffice.org/w/index.php?title=Documentation/Dashboard/Help_Style_Guide&oldid=48924"
Personal tools