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.

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!

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

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 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.

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.

FeatureX
FeatureReference