# Documentation best practices

Jump to: navigation, search
 This article describes.... todo
 The content of this article requires cleaning up to meet OD's quality standards. Check the wiki best practices for guidelines on improving article and categorisation quality.
When using a wiki for wiki organisation, it is important to conform to a consistent set of best practices which together make a generic wiki into a powerful organisational tool for describing, deploying, maintaining and using organisational systems. The aim of this article is to document and highlight the set of best practices we've developed over the last few years of applying organisation within the MediaWiki environment.

The best practices for wiki organisation play a similar role to Wikipedia's policies and guidelines, but we've named them "best practices" since its an established organisational term, apart from that, we add a few of our own specific practices.

## General wiki use

We need to guide the general use of the wiki, not just the technical aspects, otherwise there can be a tendency for users to "brain dump" information in arbitrarily named articles, which ultimately results in fragmented concepts being disbursed throughout the wiki making it difficult to find or collaborate on.

This is far more of a concern with wiki organisation than with Wikipedia because they're working within the context of an encyclopaedia which means that all articles must conform to the general guidelines of notability. When using a wiki for organisational documentation, there are less constraints on what kind of content may be created, so the conformance to best practices becomes even more important.

Brain-dumping itself is not a problem as it's often a useful way to start an article or to expand a stub article. But some important practices must be observed in the procedure, or the article will most likely stagnate and time to create it will have been wasted. Bear the following check list in mind when creating new articles:

• Check that the information doesn't belong in an existing article
• If an existing article may be appropriate, add the brain-dump to the talk page first
• Ensure conformity with naming conventions (discussed below)
• Link to the article from other related articles
• Categorise the article appropriately
• Advise other potential collaborators so they can add it to their watchlists
• Copy and paste from edit view
• Create new articles starting with red-links to avoid "orphans"
• Don't create new empty articles or "microstubs" as these will not show in Special:Wantedpages

### Training

It's absolutely imperative that all users of wikis being used for organisation have attended at least the basic workshop, and if they're also involved in collaborative projects rather than simply following standard procedures, then they will need to have done the advanced part of the workshop that covers workflow.

Some people feel that it's not practical that every member of the organisation have a general understanding of the system and how the projects are managed, but the distribution of knowledge and responsibility amongst the members is the foundation of a bottom-up organisation such as is described in the Manifesto. In a classical top-down organisation the people can focus specifically on their individual task without needing to know anything about the environment in which they work and how that functions, but the price to be paid for subscribing to this model is a constant reduction of freedom and increasing top-down influence.

### Collaboration

Discussion pages
• Use the discussion page to log chats and document agreements and conclusions etc
• Ensure the discussion page is divided into sections by topic clearly, and use the "+" action when starting a new topic
Watchlists
• Use watchlists, and tick "email changes to watched items" in preferences so that all watchlist changes are sent to email. Also the auto-watched category can be used to notify people to look at a particular article, or pages can be emailed directly.
Instant messaging

Ensure all members are on chat together and online when editing collaborative content. All instant messaging protocols such as MSN, Skype, IRC, Yahoo and ICQ have the ability for people to chat together as a group. Many chat protocols can also support voice/video over IP, but we've found that this is only useful specifically for conferences and meetings. Text-based chat can increase productivity greatly because it allows for a channel of communications to remain open without interfering with peoples ability to work or have more than one chat open at once.

We use and recommend IRC for use with Wiki Organisation rather than other chat systems for the following reasons:

• Recent changes and watchlist activity can be sent directly into an IRC channel
• The activity in the channel can be automatically logged and reflected in the wiki
• The IRC protocol and both the server and client software we use are free open source projects
• Any IRC channels can be made as secure and/or private as desired without relying on unknown corporate systems
• A local IRC server can be set up so that the members in the local LAN have their own private channel independent from the net
• The local channel can be seamlessly merged with their private or public internet channel
• As many channels as needed can be set up and remain as persistent "places to meet"
• The workflow system is able to integrate easily with the IRC channels as an additional channel of even notification

## Internationalisation

There are many messages and names used within the wiki organisation system. All such sentences and names should be defined in the wikia.i18n.php file in the svn so that it can undergo the normal method of collaboration used for internationalisation of messages.

## Templates & Transclusion

The concept behind templates and transclusion is about providing a mechanism to dynamically pass key/value parameters to an article using transclusion. Information maintained in templates provides centralized control of the design or presentation of content independent from the articles themselves. Templates on Wikipedia allow a meta language utilizing article categorization to become quickly available via the double braces syntax.

By default the Template: namespace is assumed for transcluded templates. Articles can be transcluded by specifying the Main: namespace by prepending a : in front of articles. If an article is transcluded within another from the main namespace, the template Embed should be used to visually render the transclusion.

The underlying wikitext syntax should be as simple as possible to enhance readability and encourage modification improvements. For example using spans and div tags to format content rather than using table syntax.

Templates themselves can be categorized using <noinclude>, templates which use other templates should be categorized as doing so for organizational purposes. Extension:Treeview renders a tree structure in the right hand sidebar. Nested bullet lists should themselves be categorized articles for organizational purposes.

• preload
Template documentation could be transcluded from other templates, a common method on Wikipedia is to append /doc to a template, and translude the documentation into the template using
<noinclude> {{Template Name/doc}}</noinclude>
e.g. W:Template:Userbox

Templates which are themselves designed to be transcluded with other templates should be categorized as Meta templates. Usually these are used to separate design presentation and content information.

The <noinclude> and <includeonly> tags provide class and instance functionality to templates and their transcluded instances within articles. using <noinclude> provides information such as usage documentation to the template class, <includeonly> provides additional information to the instance, such as categorization. Note that many concepts that apply to templates such as includeonly and noinclude also apply to other kinds of articles which are transcluded such as summaries.

#### Usage Instruction

Templates should have an explanation of their purpose and example of usage, the source in the following style (indenting shown only for clarification, not used in actual wikitext source code in this context).

&lt;noinclude>
{{info&#0124;This is an example of usage of the "foo" template:
&lt;pre>{{foo|bar|baz}}&lt;/pre>
}}
&lt;/noinclude>

This would produce the following output when going directly to the template page, but would not render in any articles that transclude the template.

 This is an example of usage of the "foo" template: {{foo|bar|baz}}

#### Template Categorization

Using the include style tags, categories should clearly illustrate the class/instance use of templates, for example the category Category: Template:Embed instances, and Category: Formatting templates for the class.

#### Templates vs Category

Often the question arises as to when to use a template or do it inline - usually this would be answered based on whether or not the source would need to be changed or expanded. This question becomes a bit harder to answer when the only thing in the template is a category link - i.e., should you always categorise with a template?

In general just a category-link would not be appropriate use of a template, but it comes down to maintenance, if it's likely that the category-link will be expanded later to include messages or security annotations - i.e., if your categorisation is defining a class rather than just simple grouping, you would use a template.

#### Linking vs Embedding

Linking is the power of association in MediaWiki, creating a link or reference between the content of one article and the name of another article. External links create an association to an external resource. the advantage of this is in cross referencing concepts for example using Interwiki to link definitions of concepts to Wikipedia. Embedding of templates uses transclusion to embed content from one wiki article inside another article. The downside of template transclusion is that you must create formatting so template content can be easily identified. The formatting of content can be handled by meta-templates.

#### Section zero transclusion

Some pages, such as Platform specification transclude the section 0 of other pages, the summary at the beginning before the first heading. In order to transclude part of a page, the tag <onlyinclude> can be used to surround the text that will be exclusively transcluded, to avoid transcluding the entire page. On the page that the content will be transcluded within, the template {{section zero|Pagename}} formats the transcluded content like a quote and adds a "more..." link to the full page.

#### Template packages

Organisation templates, formatting templates, recordadmin templates

#### Wikipedia templates

There is a vast resource of established templates available on Wikipedia. Selected templates should be ported and categorized. A template prefix could be assigned for all borrowed templates so that commonly named templates are unique.

Anything that is ripped off Wikipiedia should be referenced and categorized as doing so, we should also have a mechanism that converts the word wikipedia to our WIKINAME automatically so we don't have to make any changes to the template article content. If changes are made and it i deemed useful to the open source community it should be submitted back to Wikipedia. This means that a 'fork of the template is less likely to develop.

## Categories & Keywords

Categories give articles hierarchical structure the same way that folders do for files.

• Also, articles can be associated with lists of keywords which they can later be queried by.

Articles are grouped together using the links syntax '[[', and the Category: namespace . For example, any article with the wikitext syntax [[Category:Foo]], will be categorized in the category Foo. The special page Special:Categories provides a list of all categories. Categories themselves can be created using transcluded templates, which provides a central mechanism for maintaining assigned categories. The names of categories can be organised; for example, the priority categories: low, medium, high - are ordinally related.

Dynamic Page List (DPL) can be used to identify all named categories in Query:Summarized categories.

### Namespaces

A namespace is a collection of pages which have content with a similar purpose, i.e. pages where the intended use is the same. Namespaces can be thought of as partitions of different types of information within the same wiki, and keep "real" content separate from user profiles, help pages, etc. --MW:Manual:Namespace In general, a namespace is an abstract container providing context for the items (names, or technical terms, or words) it holds and allows disambiguation of items having the same name (residing in different namespaces). --W:Namespace

Namespaces modify the name of articles using the : symbol in the article name, and are used to group certain types of articles together, e.g. all articles and their corresponding discussion (talk) pages. Namespaces are predefined in MediaWiki, additional namespaces can be added in [[LocalSettings.php]. If an article name has a ':' symbol in it, and the text before it is a currently existing namespace then it will be recognised as Namespace:ArticleName. If the name does not incorporate a valid namespace then it would be recognised as Article:Name.

See also;

#### Namespaces vs Category

Namespaces are like classes and represent certain kinds of real-world class of entities such as jobs, invoices, products, orders, events, processes and roles.

We must have a good rule about when namespaces are used as opposed to just categorisation. The rule above may not be strict enough, it could be more appropriate to say that namespaces are used for articles which are used in a certain way within the environment and that if the distinction is purely conceptual it should be categorisation.

One really important aspect of namespaces in an organisation-oriented wiki is the relationship between all articles having the same title but different namespaces. The only tight relationship of this kind currently recognised in MediaWiki is between an article and its talk page. I propose that all of the articles with the same title should have a similarly strong and defined relationship where the article title represents a concept and the namespaces are the different defined instances of that concept. Note: this rule applies really to titles which are words, not phrases such as "articles containing maths".

### Semantic Annotations

• todo: Templates as object instances using semantic annotations, see OD:SMW.

SMW fits in with our organisational paradigm very well because not only can we look at its querying mechanism as an extension of the category idea, but also SMW extends the categorisation process itself by using a similar syntax to a category link which allows for arbitrary relationships instead of only that of category (a.k.a the "is member of" relationship).

Semantic annotations allow templates to exhibit queryable parameters... Annotations should not be included directly in an article, but rather within a template so that the implementation method is centralised into the template definition, rather than across many articles.

### Summaries & Section-zero

Often documentation oriented articles have an initial summary above the table of contents (i.e. before the first section). Often it is useful to transclude these summaries into other articles. Rather than creating a separate article for the summary and transcluding that into the article, it is better to use noinclude tags or a template, to allow transclusion of the article directly but using only the summary part of the content.

### Navigation

#### Sidebar

We need to have some out-of-the-box content for sidebars such as sets of tools and links etc and also personalised content like Template:RecentEdits. These should be packages so they can be quickly imported to other wikis, or kept up to date in the field by robots.

## RecordAdmin

### Projects and Organisations

We have found that often projects and organisations get used interchangeably. To avoid this, we should first consider who the client is and create a record for the client, e.g. "ultraCorp". Next, we can set up a project record which relates to that client, e.g. "ultraCorp website overhaul". We can now add as many projects as necessary that relate to that client and keep the records separate, whereby organisation/project is a parent/child relationship.

### Portals

Categories: Many of our portals are actually categories since categories are a place you go to find a member of a group of related things. If the category members are all a certain kind of record, then a much more useful and specific set of lists can be provided rather than just the usual alphabetical list of members. In this case we can hide the "Category:" part of the name using css and can redirect related articles to the category, e.g. "Worklog" redirects to Category:Activities. Also, instead of listing members alphabetically, we have a record table or search function and a range of actions along the top.

Tabs: In a portal there will be a number of useful lists of records. When there are a lot of different lists, they can be made more accessible to the user by separating them into groups arranged as a tab-set. The headings of these tabs will usually be a "general" one first which exhibits a small amount of summary and statistics oriented information, and then the rest of the tabs will usually be record types such as the user portal which has "General", "Activities", "Issues" and "Projects". Within these record type tabs are the member list queries separated by level-3 headings.

User: user pages form the personal entry point ("mini-portal") into the organisation and contain a portal to one's own information, e.g. issues, projects, hours worked so far this month, etc. This is like a kind of "Inbox" which can list various items of interest, or alternatively high level reports (pie charts, etc.), like many CRM applications.

Records as portals: Individual records viewed through templates can also behave like "mini-portals". Imagine a project record for "ultraCorp website overhaul". When looking at the record itself (rather than the "edit with form" view) one could access related issues, projects, activities, or create new issues or activities related to that project.

Portals: user, role, project, people

Queries: In our organisational wiki context, we should think of queries as an extension of the idea of a category in that its a dynamically generated list of articles which has some particular aspects in common as defined by the query. In the case of categorisation, this common aspect is simply that they are all members of the category in question. Dynamic Page List (DPL) is an extension which provides parser extension functions and tags which interface using MySQL queries directly with the MediaWiki database. Care must be taken to not overload the server's CPU and RAM with very expensive DPL queries.

• todo: Selections
• See DPL Manual for syntax usage.
• todo: queries should work like categories except that the results can render in specialised templates containing item summary or state information etc

### Record names

 Note: Milan proposed that all records should have GUID titles to avoid conflicts with normal article titles, pointing out that Records are always accessed via queries in portals and RA searches which can display their name/description fields. Another key issue regarding this is that sometimes records need to be renamed when later their old name is considered inappropriate, but this is a problem if their are other records relating to it. If all titles of records were GUID's there'd never be any need to rename them, only changing their Name field.

Record names should be left empty if they don't have any intuitive naming method in which case they'll be given a unique identifier (GUID) composed of the date and some random letters and numbers, eg. 20090231-A5T67. Examples of records best using GUID's for names are invoices and transactions. Examples of records which may not use GUID's are contacts and products - anything which has a unique title field may as well use that as its identifier.

In fact, since records should be private by default, it may be best to use GUIDs for all records. we can control how they are displayed using record tables after all, which can use any fields, such as "name" or "description" to select records by.

Exceptions to this may be "records" such as "Document" which should still have descriptive naming. Or maybe those aren't records but rather articles that use templates which can be edited with forms.

People: Record names of people should be composed of firstname and surname, but not title (as this can change)

### Field names

Try and keep field names to alpha-numeric characters and use CamelCase for consistency with existing field names.

If we make articles that have several record types in them, if the same Name is used (like Status) for two different variables, then that needs to be resolved.

## Development

### Collaboration

The wiki organisation system allows the actual work, time and tasks to be managed, but for the code itself we find it best to use tools dedicated to code management such as Subversion or Git. It doesn't matter much which one is used because code can easily be migrated from one tool to another. Currently our procedures are all set up for working with Subversion since that's what MediaWiki uses, but we may well change to Git at some point in the future because Git is more closely aligned with our decentralised philosophy. Whatever solution is adopted, there must be procedures available for setting up the software, setting up repo's, migrating to and from Subversion, and being able to view the code from a browser.

### Specifications

Without a precise description of the results required, developers cannot move forward and the project will stagnate. The kinds of descriptions they can work with include mock-up images, links to existing sites exhibiting similar functionality, or clearly defined use-case descriptions. A specification is essentially a list of requirements specifying how the client requires their software to operate and will often be bound by various constraints.

The key aspect of specification is completeness, which means that I am able to comprehend every item in the specification to a fine enough degree to be able to program it. Usually I will not even commit to the work until the specification is complete, because there's no telling how much time may be involved in the unknowns. Some of the work I do is carried out in online project management environments like RentACoder and ScriptLance. If the specification is not concise and complete when working in these sites, it is difficult to know when the job is completed which will often lead to a lengthy arbitration process, or even worse a reduced ranking which adversely affects the ability to win further project bids.

Often the client will be unable to supply a satisfactory specification and they must work with the Project Management role to create one. I may also be involved in this phase of the project, but only in the capacity of an advisor or researcher, but I wouldn't usually contribute directly to the specification unless the project is small and I am filling the project management role for it.

In the wiki environment the distinction between content and development can be difficult to clarify because much of the development often involves constructing templates and queries within the wiki environment. These requirements should be defined in the specification, but are often requested by the content management role when working on some of the more complex aspects of structured content.

## Security

• Public sites that contain private records should have their records in the Record NS and use GUID's for all types
• Pages exhibiting read restrictions should not be archived by robots (added to SS4 Aug 09)
• Sysops and other groups that access privileged information should be auto-redirected to a secure connection
• Only SSL connections should be allowed for POP, IMAP and SMTP
• The org should run its own secure SMTP server

### Private wiki practices

One issue that occurs with private wikis which are only accessible by a few users is that the job queue does not get processed often and it can take hours for links to update when templates change for example. On public wikis this is not a problem even for relatively unpopular ones because there is not shortage of requests due to all the web-crawlers and other bot traffic. Our best practice to overcome this problem for private wikis is to increase the \$wgJobRunRate from the default of 1 up to 10 or 25.

## Users and People

• whiteboard notes
• User page redirects to the Person record
• Person record is the home page for registered users, the actual wiki Main Page is for non-registered users
• Users are sync'd across wiki and accounts
• Accounts all have: wiki user, unix user, samba user, IMAP folders, email addresses
• Wiki users represent accounts not people
• Person records are used to represent people
• Some of the people have one or more associated accounts
• Some or all of the wiki users have associated accounts (depending on the org)
• All roles have one or more associated accounts
• If more than one org is involved or the org is big enough to have departments or branches, then names should be prefixed with org-name
• note: be sure to use minus not underscore as unix accounts can't have underscores

## Charging Practices

This section deals with some of the practices we've put in place after having various disagreements and problems crop up throughout the various projects we've been working on together over the years. See also the About article for more information about these issues.

Charging is done for demonstrable outcomes. Every activity should say specifically what was done. If that cannot be done then it is a good indicator that the activity is not chargeable. From the paying client's perspective, they're looking at what value has been delivered for the time they're paying for. If for whatever reason, the value delivered is lower than usual, then some of the time will need to be unchargeable. If a person is consistently delivering lower value in their role, then a lower charge-out rate will need to be accepted until the ability for that person to become more productive is achieved.

### Weekly Meetings

Weekly meetings (for us the Friday meeting) should primarily involve looking at the hours worked on the various project for that month so far. This is important so that "flogging dead horses" doesn't occur and so that current charges can be compared to budgets etc.

Also its important to summarise the actual results achieved rather than just how much work has been done, because the charges must reflect the results.

### Formal Work Sessions

If work is done towards the resolution of an issue, one person at a time can charge by agreement, for demonstrable outcomes only.

### Communications

Communications are generally not chargeable. The exception is when demonstrable progress is made on an issue as a result of communications with a client, because it is then a work session. No communications between OD crew to be charged.

### Activities with Multiple Participants

All the participants should be noted as contributing, generally these will be unchargeable, since it means the activity is probably not specifically demonstrable enough to be charged.

### False Attempts

In general false attempts and their remedial activities are unchargeable, with the time spent allocated to education. The exception is when the false attempt was genuinely unavoidable because procedure does not exist and research has failed to find an existing answer.

### Commission

We need to sort out a solid commission model so that its beneficial for associates and members to spend time getting new clients

## Projects

• Issues should be a complete list of key issues which is initially generated from the spec

## Peer teams

• Weekly check-ins
• Friday meeting, late afternoon, week catchup - plus agenda, then documentary - weekly agenda/meeting article; see weekly meetings.
• Provide opportunities for interested stakeholders to stay in the loop - transparent communication and systems
• Decide on an external contact and representative, make sure comms are signed off by the rest of the team performed by external rep
• Distinguish between peers who are involved as stakeholders in a group and people working on projects with specific roles and responsibilities
• Define early on within a project who has which roles and responsibilities
• No disagreement in front of clients, present a unified front

## Notes from OD conventions article (to be incorprorated into this)

### Workflow

• Keep main Todo Category uncluttered and containing tasks of general concern, ie not specific user's tasks
• Projects are divided up into smaller tasks which are bullet lists to cross off
• Sub-lists can form, or they could be linked out to a separate todo-article (esp. if it needs to be done by different role)
• Make task names descriptive, but not too long - like an email's subject line or an article's edit summary.
• Cross off and append: done by ~~~ at ~~~~~
eg. Get a hair cut done by Nad at 06:57, 12 Oct 2006 (NZST)
• Keep content of todo articles to a short description and a bullet list of items
• Move todo articles to Category:Done when finished
• Use the todo-article's talk page for larger descriptions of details and discussions etc
• Use the discussion requests category to indicate tasks waiting for information/decisions etc
• Use the Questions:UserName articles to direct questions requiring answers to particular people

### Article titles

• Avoid names that could be required by a more general concept.
• Forward slashes can be used to divide a name, this format keeps URL's uniform
• Whether to make them long descriptive titles, or short ones depends on the contexts of the cats and articles they're used within.
• Capital letters - Use capital first letter always except for filenames and specifics like iPod, only use other capitals for proper nouns.
• The default move operation is now rename which frees up the original title without making a redirect. Make a redirect if the original title linked to a lot or still in common use.

### Headings

• Start top level headings with "=="
• Only use the # style when its absolutely necessary to have outline-numbering that work with embedding

### Embedding

• Use the MediaWiki transclusion syntax unless you need to apply-code or embed script or something else using the XmlWiki properties
• To use MediaWiki transclusion without templates, use a preceeding : before the article name

### Content

• Article size
• Edit summary
• Minor edit
• Editing user-talk pages
• Add new comments below the existing item they are with respect to and indent one more level than that item, this way the conversation thread is clear (also such threads will migrated into the peer environment as threads).
• Add new threads/topic to the top, not bottom (I didn't get round to changing the "+" edit to do that, so don't use it), and use a ---- separator to signify the thread change.
• Use --~~~~ signiture at the end of your comment, or on next line indented to same level.
• Fix up items to conform to the conventions when you come across them

### Policies

• Login to edit: We use this policy on our wiki's not because we want to reduce accessibility in any way or to force people to register, but rather because all our regular users would frequently forget to sign in and would appear as IP addresses in the recent changes instead of as their username.