How to Document a Feature
To document a feature correctly, the documentation team needs to create a range of pages, including a ))FeatureXGlosspage (defining the feature), aFeatureXpage that lists what the feature can do, aFeatureXDocspage with step-by-step instructions, aFeatureXAdminpage with step-by-step administrative procedures and tips, and aFeatureXSettings(( page that provides a quick overview of the feature's administrative settings. For more information and examples, click the plus sign.
[+]
When documenting a feature, please create pages using the following guidelines.
In brief, each Tiki feature needs the following pages (replace FeatureX with the feature's name):
- FeatureXGloss - short glossary definition, for everyone
- Using the
INCLUDE Wiki tag, this blurb can be quickly inserted into any or all of the following FeatureX pages.
- See the Wiki syntax of Directory for an example.
- {INCLUDE(page=>DirectoryGloss)}{INCLUDE}
- FeatureX - general info, for everyone
- FeatureXDoc - what FeatureX does NOW, for users. See "How To Write Great Documentation," below, for tips.
- FeatureXDev - what FeatureX will do LATER, for developers
- FeatureXAdmin - how to configure FeatureX, for all site admins. See "How To Write Great Documentation," below, for tips.
- FeatureXSettings - site-wide configurations, for the head TikiAdmin and/or SysAdmin, when applicable
- Mainly, these are the settings made from TikiAdminSettings.
- These pages provide a quick overview of administrative sections.
- Thus, an example using Directory would be:
- DirectoryGloss
- Directory
- DirectoryDoc
- DirectoryDev
- DirectoryAdmin
- DirectorySettings
__Note: Please adopt the page(s) you're working on. To do so, go to the FeatureReference page and add your name after the feature.
How To Write Great Documentation
It's easy — just follow a few simple rules. The following guidelines are suggested for ))FeatureXDocandFeatureXAdmin(( pages. Click the plus sign to view the guidelines.
[+]
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.
- Be sure to follow the Documentation Conventions, described below.
- 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!
Annotated Example
Click the plus sign to see some documentation that implements the guidelines (presented above).
[+]
The following annotated example, drawn from WikiListDoc, illustrates these guidelines. Please see WikiListDoc 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.
➡️ Note: The above is included from WikiListGloss.
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
* | Bulleted list
|
# | Numbered list
|
| ;term:definition | Definition list |
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:
- Place the insertion point at the beginning of the line.
- Type an asterisk (*).
- Type the item's text.
- Press Enter.
➡️ Always use a numbered list for procedures, and break the procedures 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.
➡️ Note that Tiki menu items and command options are capitalized and shown in bold.
- 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.
Documentation Conventions
For consistency's sake, typographical conventions — formatting rules to follow when writing documentation — make very good sense. Click the plus sign to view the recommended conventions.
[+]
In order to have some consistency in how the Tiki documentation looks, please use the following conventions:
- boldface = a word or phrase that appears in a Tiki menu or on a button.
- Wiki syntax: __some text__ (two underscores)
- E.g., Click the preview button to see how your Wiki page will appear in its final form.
- italics = a word or phrase that the user might enter or that is variable. Italics are also used when quoting a setting from an admin page.
- Wiki syntax: ''some text'' (two single quotes--not double quotation marks)
- E.g., Enter your name into the space provided when logging in.
-
fixed proportions = Wiki code or code to be entered on a command line.
- Wiki syntax: -+some text+-
- E.g.,
mv lasttiki_release_eta_carinea_rc1 tiki
- Gender-neutral language.
- E.g., when using a pronoun to refer to a "user," use "he or she." Or, stick with the plural ("users") and then use plural pronouns ("they," "them").
- Capitalization of Tiki features
- Capitalize the names of Tiki features even if the names occur in the middle of sentences.
- Tables are useful for explaining the options in a form.
- Wiki syntax: || cell one | cell two ||
- E.g.,
| Links per page | After Tiki displays n number of links, it will direct the viewer to additional pages of links. |
- See DirectorySettings for a full example.
More information
FeatureX
FeatureReference