The Joomla! Community Magazine™

5 Ways to Document Your Joomla Extension

Written by | Sunday, 01 May 2011 00:00 | Published in 2011 May
When it comes to creating an extension for Joomla — or any type of software — documentation will always be an important part of that extension’s success.
Add a tooltip to each field Add a tooltip to each field iJoomla.com

Good documentation produces:

  • A better user experience – No one wants to submit a support ticket or post a question in a forum then wait for an answer that may never come. When your customers can find all of the information they need by reading the manual or by watching video tutorials, they’ll be much happier.
  • Fewer support inquiries – With fewer questions, you’ll spend less time and money on support. Instead, you’ll have more time and money to spend on adding new features or creating the next kick-ass extension.

5 Types of Documentation

During more than five years of Joomla development I’ve learned that when it comes to documentation, different customers have different needs. Some people love nothing more than to sit and read a manual from cover to cover. Others love watching video tutorials. A manual alone isn’t enough.

I’ve identified five types of documentation that extensions need. You should implement as many of them as you can.

If you don’t have the time to create all of them yourself, hire someone to help or ask your loyal customers to chip in in return for free upgrades or some other compensation.

1. Manual

The most basic documentation is a manual. Some users will read it from cover to cover; others will keep it for reference. However people plan to use it, the manual should always be well organized with content that’s easy to find.

The manual should always contain:

  • Cover page with your company’s name and logo, URL, extension name and links to Support, FAQ, Forum, and Upgrade.
  • Table of Contents.
  • Short overview.
  • Requirements (if applicable).
  • Install/uninstall/upgrade instructions.
  • Features and how to’s.

Be sure to include a screenshot for each feature; it’s easier to explain if you can show what you’re describing. Also make sure the text is large and avoid light text on a dark  background. Create the manual as a Word document and when you’re done, convert it to PDF.

2. Video tutorials

Video tutorials are an awesome way to explain different aspects and features of your extension. Even if you’re not a native English speaker (like me), but your English is good enough, you can still talk on video. And don’t worry about how you sound! Voices always sound a bit strange on video at first, but you soon get used to it. Use a tool such as Camtasia Studio to record yourself while you explain how your product works.

Once you’re done, in addition to placing the videos on your site, consider linking your video tutorial on the extension’s backend where it’s needed most. Your customer might not come back to your site to view video tutorials so make it easier for them. At iJoomla.com, we started adding links to our video tutorials on most of our extensions a couple of years ago and our customers really love it.

OS training recently released OSToolBar, an extension that shows a video button on your Joomla backend. It’s the same concept of the links to videos on iJoomla products but is used for general core Joomla features. I believe this is a beginning of a trend that will continue to develop and I hope will become standard in the Joomla community.

3. Tool tips

A tooltip is the small “hover box” that appears above an element when a user places the cursor on it. It’s an easy way to educate users about the functions on a page.

There are two common ways to add a tooltip on Joomla extensions:

  • Adding an info icon that shows the tooltip when hovering;
  • Adding the tool tip to the field label (Joomla’s default.)

I prefer the first approach. Few users know that they can hover over the field label and they don’t know the tooltip is present until they do hover. An icon is much clearer.

One cool approach that I take is to copy the field description from the manual. It keeps everything consistent and means that I don’t have to it write twice. I write the manual first, describe all the fields, then let my developers know which tooltip goes where.

Many developers misuse the tooltip. Instead of providing the information they need to use the element it describes, they only repeat the field label.

The right way to write your tool tip:

Describe what the field does and explain how to use it. So if you’re asking for an API, tell the user where to find it. If you’re asking the user to upload a file, tell them which file types are supported and the maximum size.

Wrong way to write your tool tip:

Repeat the field name.

4. Written Tutorials

If you know that your customers are asking similar questions, direct them to a tutorial with steps and images whenever they come up on your forum or support system. This will save you both a lot of time. Here’s an example for a written tutorial we created for iJoomla Ad agency, we've included a video as well for the ones who prefer a video.

5. Wiki

A wiki is a site or software that allows users to collaboratively create and edit web pages. You can enter the content yourself or let your customers contribute.

I haven’t had a chance to create a wiki on iJoomla.com yet, but the wikis I’ve seen other developers use have been great. A good example is the wiki page for hwdmediashare: http://documentation.hwdmediashare.co.uk/wiki/Main_Page

There are a number of wiki Joomla extensions that you can use. I haven’t tried them myself but hwdmediashar uses a stand-along called media wiki: http://www.mediawiki.org/wiki/MediaWiki.

Tips:

Keep your documentation up-to-date .

If you make changes to the extension, make sure you update your documentation as well, especially if the changes are significant

Leave it to the end.

You will be making changes to your extensions during the development — even at the last minute — so leave the documentation work to the very end, as the last step before the release.

Writing good documentation saves you time and money, and makes your customers happy. What other documentations methods are you using?

Read 17822 times
Tagged under Developers
Merav Knafo

Merav Knafo

Merav Knafo is the founder of iJoomla.com and usabilitytesting.tv, she specializes in creating high-end Joomla extensions and she is passionate about usability.