Writing User Documentation for ACF: Difference between revisions

From Alpine Linux
mNo edit summary
(delete Category:HOWTO)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Guidelines on User Documentation for ACF =
= Guidelines on User Documentation for ACF =


Many users of Alpine Linux devices may use only the ACF Web interface.
Many users of Alpine Linux devices may use only the ACF Web interface. Therefore, it is beneficial to have a clear, consistent way of documenting procedures with ACF. These guidelines can be used to write concise documents that use ACF instead of the command line.


== Basic suggestions ==
== Basic suggestions ==
Line 35: Line 35:
  ''System: '''Local Backups''' > '''Config''' > Edit Included Files: Included item(s)
  ''System: '''Local Backups''' > '''Config''' > Edit Included Files: Included item(s)
  ''System: '''Logfiles''' > '''Status''' > /var/log/messages: '''Tail'''
  ''System: '''Logfiles''' > '''Status''' > /var/log/messages: '''Tail'''
[[Category:ACF]]

Latest revision as of 16:06, 21 March 2012

Guidelines on User Documentation for ACF

Many users of Alpine Linux devices may use only the ACF Web interface. Therefore, it is beneficial to have a clear, consistent way of documenting procedures with ACF. These guidelines can be used to write concise documents that use ACF instead of the command line.

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