Documentation Conventions

In order to have some consistency in how the Tiki documentation looks, I suggest we follow these 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?
  • Should a Tiki feature (e.g., "Forums") be capitalized when referred to in the middle of a sentence?
  • Clearly, the words Tiki and TikiWiki must be capitalized because they are proper names. But my tendency would be to not capitalize features.
• When documenting a feature, use the set of Wiki pages explained on FeatureX:
  • 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
  • FeatureXDev - what FeatureX will do LATER, for developers
  • FeatureXAdmin - how to configure FeatureX, for all site admins
  • FeatureXSettings - site-wide configurations, for the head TikiAdmin and/or SysAdmin, when applicable
    • Mainly, these are the settings made from TikiAdminSettings.
  • Thus, an example using Directory would be:
    • DirectoryGloss
    • Directory
    • DirectoryDoc
    • DirectoryDev
    • DirectoryAdmin
    • DirectorySettings

Do these conventions make sense to other doc writers? What others should we use?

For an example of how this might work, please see DirectoryDoc.

More information

FeatureX
FeatureReference