The Joomla! Community Magazine™

Creating end user documentation

Written by | Sunday, 01 August 2010 15:50 | Published in 2010 August
End user documentation is key to the success of any Joomla! extension. The most popular and the most favored extensions in the Joomla! Extensions Directory have extensive documentation.

End User Documentation

Example of superb documentation - Akeeba Backup User's Guide

Documentation can take the form of online documents, PDFs, video walk-through and printed manuals. It should cover each function within your extension. Good quality documentation needs to reflect the actual functionality of the current version of the extension. Ideally it should be cross-referenced and searchable. Not surprisingly, a large number of Joomla! developers create their documentation with Joomla!.

A Review of Other Help Authoring Tools
The Google Directory of Documentation Tools

No matter which software you choose to help you create your documentation, the processes involved are always the same.

Identify your audience

This isn't as simple as it sounds. There might be the average user, the more experienced designer, a knowledgeable developer or even a system administrator. You can assume that the vast majority of your readers will not read the documentation before trying your product. Most people only turn to the documentation when something unexpected occurs and they need guidance. One user guide might not serve the needs of your entire audience.


Outline your documentation

There is no point starting without a plan. Did you start programming without a plan? Probably not. Here is an example outline.

  1. Introduction
  2. Disclaimer, Versioning and License Agreement
  3. Table of Contents
  4. Body of the Guide
    • Installation
    • Upgrade
    • Uninstall
    • Step by Step
  5. Reference Materials, Glossary and Additional Requirements
  6. Contact and Support Information
  7. Copyright and Affiliation

1. Introduction

Quickly explain the purpose of the extension. Explain what it will and will not do.

2. Disclaimer

Make very clear that you are not taking on responsibility for your user's website and you are making no warranty claims.
State the current version of your product.
State your license agreement clearly and link to the appropriate resources.

3. Table of Contents

Add to this after your guide is written and complete. With every update to your documentation, your Table of Contents will need updating.

4. Body of the Guide

This will differ for each project but here are a few points to cover

  • Installation (both automated and manual)
  • Uninstallation (both automated and manual)
  • Upgrade Process
  • Explanation of every menu/option in your extension
  • Step by step guides
    Video capture is very helpful for this. If you don't like the sound of your voice, try a program like Captivate. Still image screen capture also works well as long as you do not skip steps.
  • Points of difficulty (places where users might get off track)

5. Reference Materials

Explain any technical terms you might use in your documentation. Include links to helpful websites.
For example, if you reference RegEx then explain what Regular Expressions are and provide a link to http://www.regular-expressions.info. If you reference file permissions, take a minute and explain how to change them in your favorite FTP program.

6. Contact and Additional Support Information

If you have forums, link to them. If you have subscription-based support, link to your subscription options. If you do not plan on offering any support outside of documentation, state that clearly. Joomla! is powered by volunteers and not every third-party developer can provide support.

7. Copyright and Affiliation

If you haven't done so already, claim your copyright to both the product and its supporting documentation. Clearly state your relationship, or lack there of, to the Joomla! project


Create a consistent style for your guide

Decide how to format code. Maybe you will style clickable items in bold. Maybe your section heading will always be H2 tags. The details of your style are up to you. What is important is that you remain consistent throughout your documentation. So create your own style and stick to it!


Start documenting!

Don't try to take on the entire project at once. Break it up into smaller pieces and make it a work in progress. Most documentation is always "in progress".

Read 41542 times
Tagged under Developers

Language Switcher

Grab the Joomla! Community Banners! Spread the word!

Recommend us on Google+