Advice on how to write useful documentation.

There are two useful pieces of advice that can help improve a great deal of technical documentation.

• Explain any potentially confusing details either before you mention it the first time or immediately afterwards.
• Do not make people dig for information.

This article was inspired by the nightmare that is the current jQuery documentation.

The jQuery home page is short, seemingly easy to understand, and a nightmare. If you ignore the content above and below the home-content div, the Resources aside, and the Other Related Projects section the page contains around 200 words of useful documentation that describes what jQuery is and what it can be used for. It even contains several useful code samples.

However, it only provides enough information to confuse people.

The problem begins with the very first code block on the page, which is as follows.

$( "button.continue" ).html( "Next Step..." )

The problem is that nowhere on the page does it explain what $ means in this context. To find the answer to this question in the jQuery documentation you need to follow the jQuery Core API Documentation link on the jQuery home page. Then on the jQuery Core API Documentation page you need to follow the jQuery Learning Center link. Then on the jQuery Learning Center page you need to follow the About jQuery link. Then on the About jQuery page you need to follow the How jQuery Works link. Finally, on the How jQuery Works page you will find the following unhelpful bit of information.

Note: The jQuery library exposes its methods and properties via two properties of the window object called jQuery and $. $ is simply an alias for jQuery and it’s often employed because it’s shorter and faster to write.

There are multiple problems with this.

• I had to follow four links to get to this page.
• This paragraph is far down that page.
• The statement “$ is simply an alias for jQuery” is unclear since it does not explain what jQuery references in this context.

jQuery could mean one of the following.

• The library itself.
• The jQuery property of the window object mentioned in that paragraph.
• The jQuery() method.
• The jQuery object.

The jQuery home page would be much better and much more useful if they simply added the following paragraph immediately after the above code block.

$ is simply an alias for the jQuery() method.

There is a similar issue with every other code block on the page. The page introduces concepts without explaining those concepts on the home page and does not include any links that are actually useful in understanding the code blocks.