Documentation

Posted by Bryan Pfaffenberger 05 Oct 2003 14:29 GMT-0000 posts: 10

The following guidelines are used by O'Reilly and other top computer how-to publishers:

• Provide an overview, structured in the same sequence as the material that will follow, that tells what the feature is for. Keep this section at a high level of abstraction; for example, do not describe all the options and variations.
• For readers in a hurry, provide a quick reference section. Think: What do you always find yourself looking up?
• Begin each sub-section with a more detailed overview, explaining what the feature does in more detail, including where you go to start, what you have to do, how it works (briefly, and what options are available. (You will probably have to test the feature to find out. There are tons of undocumented features! Talk to developers and examine the code, too.)
• Remember, people don't read on the Web. They scan! Make your text more readable by doing the following:
  • ALWAYS use a numbered list, with step-by-step procedures, for ALL the procedures you describe.
  • Use white space effectively.
  • Use bold for key words.
• Ultra-important: Think of everything that can go wrong! ALWAYS include a troubleshooting guide for EVERY section, and tell how to SOLVE the problem.
• Consider how Tiki might work differently depending on the administrative options that have been chosen. Indicate how administrative options might affect what the user sees!

The following annotated example, drawn from TikiListDocs, illustrates these guidelines. Please see TikiListDocs for the non-annotated, full-length version. For help, questions, and suggestions, write to Bryan.

Creating bulleted, numbered, and definition lists

➡️ Use action words ("creating," "changing," "removing," etc. in titles.

In Wiki pages and other contexts that support Wiki formatting (including articles, forums, and blogs), you can easily create bulleted, numbered, and definition lists. In numbered lists, Tiki numbers the items automatically. You can also create nested lists. The following sections explain the details; see the Quick Reference for an overview. Scroll down to Help! if something goes wrong.

➡️ Note how the above section anticipates and replicates the structure of the following sub-sections. Note the level of abstraction and generality.

Quick reference: List formatting codes

Tip If you forget which of the above list-formatting codes to use while you're editing, click the Wiki Quick Help tab. This tab appears when you're editing a Wiki page.

➡️ Keep this short.

Creating a bulleted list

Use a bulleted list whenever you're editing a Wiki, blog, or articles page, and you want to list items of equal or comparable importance.

➡️ Describes (a) where to go to start and (b) what this feature is for

If you type an asterisk (*) at the beginning of a line, Tiki places a bullet (a black dot) at the beginning of the line. The line is indented and formatted with a hanging indent, so that second and subsequent lines are indented and aligned with the first line.

➡️ Describes how this feature works

To create a bulleted list, do the following:

1. Place the insertion point at the beginning of the line.
2. Type an asterisk.
3. Type the item's text.
4. Press Enter.

➡️ Always use a numbered list for procedures, and break them down into steps.

Did something go wrong?

• If you don't see the bullet, and the line appears in a strange-looking typewriter font that goes on without breaking properly, you left a space at the beginning of the line. Click Edit, delete the space, and click Save.

• If there's too much white space around the list, delete any blank lines you may have entered before or after the list.

➡️ Try to think of everything that can go wrong!

Note Administrators can configure Tiki so that beginning-of-line spaces are not interpreted as the beginning of preformatted (monospace) text. On the Application Menu, click Admin and click the Wiki tab. Uncheck the Automonospaced Text option.

➡️ Consider how Tiki might work differently depending on the administrative options that have been chosen. Indicate how administrative options might affect what the user sees!