Difference between revisions of "Writing User Documentation for ACF"

From Alpine Linux
Jump to: navigation, search
(Created page with '= Guidelines on Writing User Documentation for ACF = Many users of Alpine Linux devices may use only the ACF Web interface. == Basic suggestions == *Write names and labels ''as...')
 
(added details)
Line 6: Line 6:
 
*Write names and labels ''as they appear in ACF'', such as "DNScache" instead of dnscache.
 
*Write names and labels ''as they appear in ACF'', such as "DNScache" instead of dnscache.
 
*Avoid using extra nouns such as "menu option," "tab," "section," etc. for simplicity. The formatting below should be sufficient.
 
*Avoid using extra nouns such as "menu option," "tab," "section," etc. for simplicity. The formatting below should be sufficient.
 +
* Specify the entire navigation, so that the user can follow the instructions no matter where he starts.
  
 
== Formatting ==
 
== Formatting ==
Line 11: Line 12:
 
Here is an example of the suggested formatting:
 
Here is an example of the suggested formatting:
  
 +
''System: '''Local Backups''' > '''Status''' > Commit Changes: '''Commit'''
  
''System: '''Local Backups''' > '''Config''' > System Info: Media for Commit''
+
Below is the formatting for common items in user documentation. All navigation strings should be in ''italics'' (or in plaintext, use forward slashes <code>/NAVIGATION > EXAMPLE/</code>).
  
When describing an page or procedure in ACF, user documentation may refer to items such as:  
+
*Menu Choices, Tabs, Buttons, Links
*menu choices
+
**Any text the user needs to click on should be in '''''bold (italic) typeface''''' (or in plaintext, use asterisks <code>*BUTTONNAME*</code>). The text should then be followed by a greater-than symbol ">".
*tabs
+
**Links may be preceded by a label and a colon ":".
*section headings
+
*Section Headings
*buttons
+
**Headings should be followed by a colon ":".
*links
+
*Check Boxes
*check boxes
+
**Check boxes should be followed by ''[X]'' for selected, and ''[_]'' for unselected.
*fields
+
*Fields
 +
**Field names have no special formatting.
 +
*Drop-down Boxes
 +
**Use a greater-than symbol ">" between the label of the box and the option to choose.
 +
 
 +
=== Examples ===
 +
''System: '''Local Backups'''
 +
''System: '''Local Backups''' > '''Status''' > Commit Changes: Simulate a commit [X]
 +
''System: '''Local Backups''' > '''Status''' > Commit Changes: Simulate a commit [_]
 +
''System: '''Local Backups''' > '''Config''' > System Info: Media for Commit > usb''
 +
''System: '''Local Backups''' > '''Config''' > Edit Included Files: Included item(s)
 +
''System: '''Logfiles''' > '''Status''' > /var/log/messages: '''Tail'''

Revision as of 20:53, 29 May 2009

Guidelines on Writing User Documentation for ACF

Many users of Alpine Linux devices may use only the ACF Web interface.

Basic suggestions

  • Write names and labels as they appear in ACF, such as "DNScache" instead of dnscache.
  • Avoid using extra nouns such as "menu option," "tab," "section," etc. for simplicity. The formatting below should be sufficient.
  • Specify the entire navigation, so that the user can follow the instructions no matter where he starts.

Formatting

Here is an example of the suggested formatting:

System: Local Backups > Status > Commit Changes: Commit

Below is the formatting for common items in user documentation. All navigation strings should be in italics (or in plaintext, use forward slashes /NAVIGATION > EXAMPLE/).

  • Menu Choices, Tabs, Buttons, Links
    • Any text the user needs to click on should be in bold (italic) typeface (or in plaintext, use asterisks *BUTTONNAME*). The text should then be followed by a greater-than symbol ">".
    • Links may be preceded by a label and a colon ":".
  • Section Headings
    • Headings should be followed by a colon ":".
  • Check Boxes
    • Check boxes should be followed by [X] for selected, and [_] for unselected.
  • Fields
    • Field names have no special formatting.
  • Drop-down Boxes
    • Use a greater-than symbol ">" between the label of the box and the option to choose.

Examples

System: Local Backups
System: Local Backups > Status > Commit Changes: Simulate a commit [X]
System: Local Backups > Status > Commit Changes: Simulate a commit [_]
System: Local Backups > Config > System Info: Media for Commit > usb
System: Local Backups > Config > Edit Included Files: Included item(s)
System: Logfiles > Status > /var/log/messages: Tail