Creating end user 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.
- Introduction
- Disclaimer, Versioning and License Agreement
- Table of Contents
- Body of the Guide
- Installation
- Upgrade
- Uninstall
- Step by Step
- Reference Materials, Glossary and Additional Requirements
- Contact and Support Information
- 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".
Some articles published on the Joomla Community Magazine represent the personal opinion or experience of the Author on the specific topic and might not be aligned to the official position of the Joomla Project
By accepting you will be accessing a service provided by a third-party external to https://magazine.joomla.org/
Comments