PmWiki /
DocumentationGuidelinesreaders, authors (basic)
The essence of good instruction is knowing what details to leave in and which to leave out.
-Pm, in message to the the pmwiki-users mailing list
English is a very flexible language and there is usually more than one way to write anything. However, good writing benefits from being strongly consistent and for readers to be able to easily skim and absorb the content without having to think about it. In general this is no "right answer" on how to write, however, with a project involving multiple contributors it makes sense to define some "house style" guidelines and request that as far as possible that authors consider these when authoring pages Quick PointsThese are the broad guidelines used for writing documentation pages for PmWiki.
DetailsMany 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 levelIndicated audiences are not intended to be exclusive or constraining; they just provide 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.
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):
Suggested markup (in the page):
How to provide keywords to assist with searchesUse this markup: (:keywords word, ...:)
Example for this page: (:keywords Documentation Guidelines, Documentation, Howto Document:)
Add keywords before any visible content on the page. How to make sure links workNot 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 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 possibleIn "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" documentationPmWiki 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"
Suggested styling for wiki links and link textLink text spacingPmWiki has a very flexible approach to creating links and this can even be altered through certain configuration settings. However, there is a general style philosophy that we use throughout the documentation which is as follows:
"Proper Nouns" written in Camel CaseThe following are defined to be single words and should be written consistently in camel case as follows:
Link text capitalisationCapitalisation is less well defined and is left up to the author's judgement. However, the following guidance is offered:
Use whitespaceThe judicious use of whitespace assists considerably in the authoring and maintenance of pages. At a minimum the following is suggested
For example
NOTE This page may have a more recent version on pmwiki.org: PmWiki:DocumentationGuidelines, and a talk page: PmWiki:DocumentationGuidelines-Talk. |