Access Keys:
Skip to content (Access Key - 0)

How to Write Great Wiki Pages

Follow the archetype below when writing new technical documentation for the Wiki. This format encourages you to write concisely and effectively. Feel free to edit this page and copy-and-paste the content below into your new document. Use one page per topic or task.

Name of Concept or Technology

If this is strictly a process or task, use a concise description of the process as the article title. Explain what this command, program, feature, or process is, and where it is used. Let readers know that this is the right process to follow for their situation.

Prerequisites

What are the prerequisite conditions for this task? Which versions of the software does this apply to? Which platforms? Also provide definitions of technical terms that users need to know in order to follow the instructions.

Instructions

  1. Start with the first action the user takes to solve the problem or accomplish the task. Try to avoid sub-steps if possible - refine your list to each separate task a user needs to execute.
  2. This is the next item in the list, chronologically.
  3. Etc., etc., until the last step.

Results

Explain briefly to users how they will know that the process was successful. Sometimes this is obvious; if so, leave this section out.

Examples

Reserve your sample code, example text, and screen shots for this area unless it is absolutely necessary to include them above.

Troubleshooting

What can go wrong? Cover common and known problems, then cover how you can discover the root of a problem (logging, debugging symbols, etc.)

Related Items

  • This bulleted list contains other processes that the user should follow after this.
  • It also contains links to external resources, and either links for or names of other articles that could be useful.

This documentation is maintained by the Pentaho community, and members are encouraged to create new pages in the appropriate spaces, or edit existing pages that need to be corrected or updated.

Please do not leave comments on Wiki pages asking for help. They will be deleted. Use the forums instead.

Adaptavist Theme Builder Powered by Atlassian Confluence