Writing User Documentation for ACF: Difference between revisions

From Alpine Linux
mNo edit summary
(better introduction)
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 ==

Revision as of 13:16, 1 June 2009

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