• View
• Edit
• History
• Print
• Backlinks

Documentation Guidelines

Quick Points

These are the broad guidelines used for writing documentation pages for PmWiki.

• Omit needless words.
• Use simple markup for documentation. (KISS)
• Don't rely on WikiWord links; use [[WikiWord]] whenever a link is needed.
• Use PmWiki:PageName or Cookbook:PageName to link to pages that aren't part of the distribution (otherwise the links will not work on sites other than pmwiki.org).
• Mark incomplete pages or documents needing review with [[!DocumentationToDo]] or [[!Update me]]. Place the category marker near the section needing work.
• Use http://www.example.com/ as the prefix for example URLs.
• Use example names for values in code examples, like GroupName, PageName, label=Search.
• Use ->[@ or -->[@ to indent code examples.
• Place any documentation-specific styles in PmWiki:GroupHeader.
• Don't use table markups for things other than tables.
• Use the (:keywords:) markup to provide keywords to assist with searches.
• Indicate the intended audience and difficulty level of your documentation.
• Use headings !! and !!! to divide your page into manageable "chunks". Use "sentence capitalization" for headings (capitalize only the first letter of the heading and any proper names).
• Use "newspaper-style" writing where possible. Facts first. Story later. Punchy. (See below)
• Do not "sign" documentation unless it is a personal opinion you don't want changed.

Details

Many of the quick points above need no further explanation, but the items below provide more details and "how to" information.

KISS (Keep It Short & Simple)

Keep the markup in the documentation simple. The PmWiki documentation is a self-demonstration of what can be done with wiki markup, and like any collaborative document it needs to be accessible to many authors. It's important for the markup to be readable - not just the rendered output.

How to indicate audiences and document difficulty level

Audiences are not intended to be exclusive or constraining, they are just a convenient way for a user to decide what is relevant to them. And, of course, a convenient way for authors to indicate who their docs are intended for. For a full description see Audiences.

• The keywords for audiences are readers, authors, admins (and all for all three)
• The keywords for difficulty levels are basic, intermediate, advanced.

There is no direct relation between the audience and the level - audience classifies the individuals accessing the wiki, while level indicates the relative difficulty of the material.

Suggested markup (near or at the top of the page):

%audience% readers, authors (basic)

How to provide keywords to assist with searches

Use this markup:

Example for this page:

Add keywords before any visible content on the page.

How to make sure links work

Not every page that is in the PmWiki group here or on pmwiki.org ends up in the distribution. Beware of creating links to non-distributed pages.

• Use either [[PmWiki:PageName]] or [[Cookbook:PageName]] markup for links to pages that may not be included in the PmWiki distribution.
• Links from a documentation page to a cookbook recipe should be specified as Cookbook:PageName and not [[Cookbook/PageName]].
• Don't rely on WikiWord links, use [[WikiWord]] markup.Not every wiki has WikiWords enabled, so when writing documentation if a WikiWord is intended to link to another page then enclose it in double brackets as [[WikiWord]]. Not every occurrence of a WikiWord needs to be a link -- generally just the first is sufficient.

Use headings for information "chunking"

A long page of unbroken text can discourage readers. Use headings to break your page into sensible chunks. Headings allow readers to quickly find the information they are seeking.

Use "newspaper-style" writing where possible

In "newspaper-style" writing, you tell the whole story right at the start and then elaborate on the details later. This allows readers to get a quick appreciation of the subject at hand - and for many, that will be enough. Anyone looking for more discussion or examples reads further to find them. In newspapers, the whole story is usually told in the first paragraph. Newspapers use short sentences. The sentences are "punchy".

Do not "sign" documentation

PmWiki makes it very easy to "sign" your contributions by inserting ~~~ in the edit window. Signing is appropriate when you are posing questions or expressing a personal opinion. Most authors are very reluctant to edit signed material. However, documentation generally is not a personal opinion, and editing should be encouraged. The curious can use the history view to see who said what.

Some suggested text "styles"

• to indicate a file name, use "emphasized" markup.

''filename.ext'' or ''local/config.php''

• to indicate a directory name alone, use "emphasized" markup and include the trailing slash (/).

''cookbook/''

Documentation

• Adding Reference and Resource Links
• Table of Content
• Adding comments

NOTE
Some of the discussions behind these guidelines are preserved on the PmWiki:DocumentationGuidelines-Comments page. For convenience all further comments to this page could be made here PmWiki:DocumentationGuidelines-Comments