version=pmwiki-2.2.15 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/532.5 (KHTML, like Gecko) Chrome/4.1.249.1045 Safari/532.5
author=simon
charset=ISO-8859-1
csum=adhere to guidelines, add whitespace section
host=202.37.32.2
keywords=Documentation Guidelines, Documentation, Howto Document
name=PmWiki.DocumentationGuidelines
rev=86
targets=PmWiki.WikiWord,Category.Category,PmWiki.WikiStyles,PmWiki.GroupHeader,PmWiki.Tables,PmWiki.Audiences,PmWiki.BasicEditing,PmWiki.DocumentationGuidelines,Category.FurtherDocumentation,PmWiki.DocumentationGuidelines-Comments
text=(:Summary: Broad guidelines used for writing PmWiki documentation:)%0a(:keywords Documentation Guidelines, Documentation, Howto Document:)%0a%0a->''The essence of good instruction is knowing what details to leave in and which to leave out.''%0a-->-Pm, in message to the the pmwiki-users mailing list%0a%0aEnglish 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.%0a%0aIn 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%0a%0a!! Quick Points%0a%0aThese are the broad guidelines used for writing documentation pages for PmWiki.%0a%0a* Omit {-needless-} words.%0a* Use simple markup for documentation. ([[Wikipedia:KISS_principle|KISS]])%0a* Don't rely on [[WikiWord]] links; use [@[[Wiki Word]]@] whenever a link is needed.%0a* Use [@[[PmWiki:Page Name]]@] or [@[[Cookbook:Page Name]]@] to link to pages that aren't part of the distribution (otherwise the links will not work on sites other than pmwiki.org).%0a* Mark incomplete pages or documents needing review with [[category/]] marker [@[[!Documentation To Do]]@] or [@[[!Update me]]@].  Place the category marker near the section needing work.%0a* Use http://example.com/ as the prefix for example [=URLs=]. '^[[http://www.rfc-editor.org/rfc/rfc2606.txt|#]]^'%0a* Use example names for values in code examples, like ''GroupName'', ''PageName'', label=''Search''.%0a* Use [@->[@@]  or [@-->[@@]  to indent code examples. %0a* Place any documentation-specific [[PmWiki/Wiki Styles|styles]] in [[PmWiki:Group Header]].%0a* Don't use [[PmWiki/Tables|table]] markups for things other than tables.%0a* Use the [@(:keywords:)@] markup to provide keywords to assist with searches.%0a* Indicate the intended [[PmWiki/Audiences|audience]] and difficulty level of your documentation.%0a* Use [[PmWiki/Basic Editing#headings|headings]] [@!!@] and [@!!!@] to divide your page into manageable "chunks".  %0a* Use "sentence capitalization" for headings (capitalize only the first letter of the heading and any proper names).%0a* Use "newspaper-style" writing where possible. Facts first. Story later. Punchy. (See below)%0a* Do not "sign" documentation unless it is a personal opinion you don't want changed.%0a%0a%0a!! Details%0aMany of the quick points above need no further explanation, but the items below provide more details and "how to" information.%0a%0a%0a!!! KISS (Keep it short & simple)%0aKeep 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.%0a%0a%0a!!! How to indicate audiences and document difficulty level%0aIndicated 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]].%0a* The keywords for audiences are '''readers, authors, admins''' (and '''all''' for all three)%0a* The keywords for difficulty levels are '''basic, intermediate, advanced'''.%0aThere 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.%0a%0aSuggested markup (near or at the top of the page):%0a(:markup class=horiz:) %0a(:Audience: readers, authors (basic):)%0a(:markupend:)%0a%0aSuggested markup (in the page):%0a(:markup class=horiz:) %0a%25audience%25 readers, authors (intermediate)%0a(:markupend:)%0a%0a%0a!!!How to provide keywords to assist with searches%0aUse this markup:%0a->[@(:keywords word, ...:)@]%0aExample for this page:%0a->[@(:keywords Documentation Guidelines, Documentation, Howto Document:)@]%0aAdd keywords before any visible content on the page.%0a%0a%0a!!! How to make sure links work%0aNot 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.%0a* Use either [@[[PmWiki:Page Name]]@] or [@[[Cookbook:Page Name]]@] markup for links to pages that may not be included in the PmWiki distribution.%0a* Links from a documentation page to a cookbook recipe should be specified as [@Cookbook:Page Name@] and not [@[[Cookbook/Page Name]]@].%0a* Don't rely on WikiWord links, use [@[[Wiki Word]]@] markup.Not every wiki has [[Wiki Word | WikiWords]] enabled, so when writing documentation if a WikiWord is intended to link to another page then enclose it in double brackets as [@[[Wiki Word]]@]. Not every occurrence of a WikiWord needs to be a link -- generally just the first is sufficient.  %0a%0a%0a!!! Use headings for information "chunking"%0aA 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.%0a%0a%0a!!! Use "newspaper-style" writing where possible%0aIn "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".%0a%0a%0a!!! Do not "sign" documentation%0aPmWiki 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 [[Documentation guidelines?action=diff| history]] view to see who said what.%0a %0a%0a!!! Some suggested text "styles"%0a* to indicate a file name, use "emphasized" markup.%0a(:markup:) %0a''filename.ext'' or ''local/config.php''%0a(:markupend:)%0a* to indicate a directory name alone, use "emphasized" markup and include the trailing slash (/).%0a(:markup:) %0a''cookbook/''%0a(:markupend:)%0a%0a%0a!! Suggested styling for wiki links and link text%0a%0a!!! Link text spacing%0a%0aPmWiki 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:%0a%0a* In general minimise the use of CamelCase, ie prefer [=[[page directives]]=] to [=[[PageDirectives]]=]%0a* There are a number exceptions where CamelCase is preferred and these are listed separately below%0a%0a!!! "Proper Nouns" written in Camel Case%0a%0aThe following are defined to be single words and should be written consistently in camel case as follows:%0a%0a* PageList%0a* WikiWikiWeb%0a* ChangeLog%0a* WikiStyles%0a* InterMap%0a%0a!!! Link text capitalisation%0a%0aCapitalisation is less well defined and is left up to the author's judgement.  However, the following guidance is offered:%0a%0a* When referring to a page name by its title, use sentence case for the name.  Example:  [@For more information, see [[Page directives]].@]%0a* When using text in a sentence that happens to correspond to the name of the page, follow the capitalization rules for the sentence.  Example:  [@PmWiki supports a large number of [[page directives]].@]%0a%0a!!! Use whitespace%0aThe judicious use of whitespace assists considerably in the authoring and maintenance of pages. At a minimum the following is suggested%0a* leave a blank line before headings%0a* use a single space character after list characters%0a%0aFor example%0a(:markup class="horiz":)%0a%0a!!!!!! Heading with preceding blank line%0a* bullet list with leading space%0a# numbered list with leading space%0a-> indent with leading space%0a(:markupend:)%0a%0a----%0a[[!Further documentation]]%0a* Adding reference and resource links%0a* Table of contents%0a* Adding comments%0a%0a%0a----%0aNOTE \\%0aSome 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]]%0a
time=1272323571