Hints on good content

When creating a new wiki page it often helps to think about the various W-questions to structure the content and to ensure all necessary information is available.

Think about these questions and combine them with the hints on good style when creating new pages in the wiki.

What is the page about? A wiki page should always introduce the topic and situate the reader. This is generally done best in a couple of introductory paragraphs.

Of course this is also most important question to answer throughout the whole page.

Who's the target audience? Keep in mind who you're writing for. For example documentation differs when you're writing for developers or end users.

When targeting multiple types of users, you can try to separate the information. Either by using different pages or even namespaces, or by having different sections in a single page. When doing the latter, put the information for the larger group first. Eg, end user documentation before developer docs.

Examples:

• We have a development manual, separate from the end user docs
• Plugin pages sometimes have a separate development section. For example the oauth plugin

Why is it as it is? Explaining the history of decisions that lead to the current state of affairs may improve understanding of the topic at hand.

Examples:

• Why struct instead of data explains how the struct plugin came to be and what shortcomings of the previous plugin it tries to solve

When does the content apply? Any preconditions a page might have should be clearly communicated.

Where to find more information? Wikis live by interlinking the content. Think about what concepts in your page may need further explanations and create links for them. Add links to related content. Think about from where your page should be linked.

Examples:

• The page for the search_nslimit configuration option shows how to link to other concepts in the main content and also has a “See also” section with a list of related links