Is Your Product's Documentation Good Enough?

In the real world, when we buy a phone, or a microwave or a washing machine, it comes with a quick start guide, a user guide, some technical documentation, and other similar stuff.

Without these documents, we’ll have to learn how to use the product leveraging solely on the ‘trial and error’ method – which is not a pleasant user experience at all.

The same is true for the products and tools made from web developers.

In the last few years we have witnessed huge explosion in the web development world.

There are a vast variety of great projects out there. A deluge of plugins, libraries, frameworks, tools, and services have been created by smart people showing great insight and skill.

But there is one problem: many — perhaps most — lack of good documentation. No matter how great is a particular product might be, if it has poor documentation, we’re unlikely to use it fully and properly.

The goal of this article is to address the importance of having a good documentation both for the web developers, and for the users.

I mainly target programming products such as code libraries, plugins, and so forth, but all said below can be easily adapted to any kind of product or service. The principles are the same.

Let’s see them.

The Three Steps to the Great Success

In the web development world there are three steps leading to great success.

Creating great product. First and foremost, you need to have something useful and valuable to propose to the people out there. It can be a product or a service, but in either case it must be of great quality.

Another important factor is the ease of use. Even a great product will bleed its value, if it’s difficult for people to use it. Completing this first step is a great milestone, but you must not stop here as some web developers do.
Writing great documentation. The second step is to write documentation for your product or service. Just imagine that you are in a beautiful but unknown country.

In order to see its sights you’ll need a guide to learn where they are, and a map showing you how to get there. The guide and the map from this example are much similar to your product’s documentation.
Offering great support. Lastly, you need to offer genuine support for your product or service. Even with a good map and a proper guide at your disposal, there will be occasions where you’ll need guidance from real person to show you the right direction.

That’s what support is all about. If you’re done the previous two steps well then doing this one will be much easier.

Given the above three steps we can easily deduce the magic formula for great success:

Great product + Great documentation + Great support = Great success

Simply enough, right?

Why Do You Need Good Documentation?

A man sketching notes in a sketchbook — Sailing “Footprints: Real to Reel” (Ronn ashore)

Good documentation does two important things.

On one hand, it adds value to your product. A well-documented product is always preferred to that with poor documentation; because it’s more complete, easier to use, and thus, far more useful.

On the other hand, it reduce the need of support, because the more complete your documentation is, the less likely is users to have issues with your product.

Another important thing is the fact that a well-written documentation increase your reputation. How? Poor documentation can allow potential users to leak away to your competition, whose product may not be as cool as yours, but can be better documented. If I’m a user and see that your product’s documentation sucks, then do you know what I’ll be thinking of? If you don’t care about your own product, why should I? I’ll switch to someone else’s product — someone who cares about their product and who does all possible in order to create a pleasant user experience for me – that is, making its product easier to use by providing a comprehensive documentation. The natural conclusion of the above is, if users see that you respect them and their time by arming them with quality documentation, then they, in their turn, will respect you. What is it that differentiates a professional from an amateur is their attention to the detail. Providing a good documentation is one such detail. When you create a great product, it’s pretty tempting to stop here thinking that it’s more than enough, and that your product will speak about itself automatically. But this is not the truth. What is the benefit of your super-duper product if nobody knows how it’s supposed to be used? Null. So, if you want your product to be actually used, then you need to tell the users how.

So, What Is Good Documentation?

What follows is a set of conditions and requirements needed for a particular documentation to be classified as truly good.

Good documentation does several things:

It tells what the product is and what can be useful for (its definition and purpose).
It tells the difference from other similar products (if such exist) and what makes it unique.
It tells users how to get started with the product.
It tells users how the product can be used in real world projects (from simple to complex ones).
It tells how the product can be used in the best possible way (best practices).
It gives plenty of examples and demos for the product’s uses.

Good documentation must be:

Complete. Web developers must provide documentation for every feature and every aspect of their product, thus the latter to be used fully and properly. Everything which, if it’s omitted, will prevent user’s understanding, must be added.
Concise. The product documentation must be written in such a way which removes all redundant things. Everything which is included, but if it’s omitted, won’t prevent user’s understanding, must be cut.
Organized. Every web developer must bear in mind that randomly collected tutorials and resources – from here and there – cannot provide a systematical, logical, clear, and easy to follow guidance. All documentation’s content must be easy to follow and to navigate through, with gradual complexity, and clear hierarchy.
Up-to-date. Web developers always must provide actual documentation for the most recent version of their product. No excuses here!

What Is Fake, or Pseudo Documentation?

In the above section we’ve seen what good documentation is, and knowing that we can easily grasp its opposite: poor, or bad documentation.

What I’m going to expose here though, is something different. I call it fake, or pseudo documentation.

And the best way to explain what I mean is to give you a couple of examples.

API reference

As its name suggests, this is just a ‘reference’ or perhaps a ‘catalog’.

The only question it answers is: ‘What?’. What methods it contains, what properties they have, and so on.

There is no ‘How?’ question in it at all.

It doesn’t shows you how to use all these methods and properties. It just outlines them, in the same manner as a table of content outlines the book’s content. Its purpose is to help you when you’ve already learned the product (or respectively read the book).

It can’t teach you how to use the product. It only gives you an overview of its features and capabilities.

So, if you think that by providing only an API reference for your plugin or library, you are offering real documentation, you better think twice.

Documentation placed inside a code file

Some web developers tend to use comments inside their code files as a documentation source.

This practice is frankly wrong.

First, because this isn’t the true purpose of the comments, and second, because it makes the learning process difficult.

To open the code file when I need instructions to do something is the same as if I must open my piano to see the notes I want to play (because some ‘clever’ person has decided to print them inside).

Moreover, superfluous comments makes the code hard to read and maintain. The product and the documentation must be separated in the same way, and for similar reasons because of that we separate our HTML, CSS, and JavaScript files.

Generally speaking, every time when some web developers (most likely the lazy ones:)) try to ‘cheat’, the net result is fake documentation.

Who Is Responsible for Creating Your Product’s Documentation?

A good question, isn’t it? So, who is responsible? You, of course. As a creator, you are the person who best knows your own product and how it can be used in real world projects.

You don’t have to depend on the community and other people to write documentation and tutorials for your product. This is for several reasons.

First, third party resources, collected from here and there, are not consistent enough. They cannot provide a clear, logical, and integral learning experience.

Second, third party tutorials and articles are not enough reliable. They can be incorrect, outdated, or even deleted at some point of time.

And third, letting someone else to do your job can also discredit your reputation.

What Components a Good Documentation Consists Of?

A good documentation can consists of many different components. It’s the job of product’s author to decide which ones to include. To make this task easier I can propose the following list with some fundamental components:

Getting started section – One of the first things you must do in your documentation is to provide an adequate answer to the user’s question: ‘How to get started?’. This is important because it helps people to get confidence and gives them a starting point for further learning.
User guide/manual – If your product is fairly complex, then this component is absolutely required. It’s a type of documentation which gives users comprehensive information on how a particular product can be and/or must be used.
Examples/Demos – This is an extremely important component. If we paraphrasing the famous expression – ‘One picture worth thousand words.’ – we can say that, one shown example is better than thousand said instructions. So, the main principle here is: show, don’t tell.

Examples/Demos give a real sense about the product and its usage. Almost every instruction, especially a complex one, must be accompanied with an appropriate example.
Code playground – This component offers a ready-to-go environment where users can start toying with your product immediately. It’s great for quickly trying things out. This is important because, for novice users – who don’t know yet whether they’re going to use your product – setting their own working environment can be a bit tedious. To some degree, this is similar to the ‘try before you buy’ concept.
Slide presentations – Slides are an elegant, concise, and easy to follow method for explaining a topic, or a concept.
Tutorials – These are one of the widely used and effective ways for teaching. You may think of them as short guides/manuals focused on more narrowed topics.
Screencasts – Some people prefer video instructions instead of written ones. For them you can offer video tutorials. And also, some topics can be better explained if they are in video format. The above principle – show, don’t tell – is of equal validity here.
Cookbooks – These are especially useful when you need to provide solutions to particular or common problems. Instructions in a form of recipes are clear and concise, and users can pick only those they need.
API reference – As I said earlier this solely can’t be described as true documentation, but yet it’s an important part of it. The important thing here is how you present the API. It must be produced in a clear and easy to spot way, with easy to use navigation, and also with availability to search for particular method or property.
FAQ pages/sections – If you need to clarify some things about your product, or anything related to it, then it’s a good idea to offer a FAQ page or section.
System requirements – Before users to have your product up and running they need to know whether it’s actually possible for them. So, make sure that this information is clearly stated and put on visible place.
Change logs/Release notes – Seeing the path of your product, from its conception to its recent implementation, can be very useful to users. For example, knowing what WordPress functions are deprecated, and what are added in its newer version, allows you to make the required changes to your theme thus making it up-to-date.
License information – This component tells users where they can use your product and under what conditions.

Of course, the above list is not fully complete, but it gives you a good foundation to build on. How many components you will use depends of your project’s complexity.

If you have some small utility library consisting of several API methods, including all of the above suggestions will be far too much. You need to decide on your own.

But in all cases you need to keep in mind one thing: there is no such a thing as perfect documentation.

So, no need to be perfectionist. Just good enough is all you need to achieve.

Where Are Examples of Good Documentation?

Below are some examples which I consider as having a good documentation.

To be honest, most don’t meet all the criteria mentioned above, but are much closer to them than many others out there.

The list is minimal and only for illustrative purpose. If you think that someone’s product documentation is leaved unmentioned, please feel free to add it in the comments below.

Less

Less is an extremely useful product (a CSS preprocessor) widely used in all kind of projects which involve using CSS.

Besides that, it has a great documentation too. It offers a getting started section, fully documented language features, complete reference to its built-in functions, as well as a page dedicated to its usage.

The latter gives plenty of useful information about Less usage via command line and in the browser, browser support, Less compilers, editors with Less support, and frameworks where Less is used.

jQWidgets

jQWidgets is one of the most feature complete and universal jQuery-based widget libraries.

Not only it’s a great product on its own, but it has also a great documentation. Every single widget is clearly documented.

The API for every widget provides examples for each property, event, and method; plus interactive examples at jsfiddle.

Besides the widgets there is also information on how the library can be integrated with other popular products such as KnockoutJS, Bootstrap, WordPress and Joomla, PHP and ASP.NET, PhoneGap, and so on.

And on top of this, there are tons of demos for every widget with provided source code, which makes the learning process extremely fun, easy, and productive.

KnockoutJS

KnockoutJS is another great product (a JavaScript library) with comprehensive documentation. It offers demo video, live examples, interactive tutorials, and least but not last a thorough guide describing its features in detail .

qooxdoo

qooxdoo is an universal JavaScript framework. It provides versions for web, desktop, mobile, and server. Every version is greatly documented.

For example, qooxdoo desktop has full API reference, complete user manual available also as a pdf file, getting started and FAQ sections, and so on.

Also it offers some interactive tutorials, code playground, widgets showcase, widgets browser, and demo browser with many examples.

CodeIgniter

CodeIgniter is a great PHP framework with a small footprint.

At its home page you can get immediately answer to what it is and whether it’s appropriate for your project and requirements. And, in its user manual you can find detailed information about the framework: Getting Started, installation instructions, a short tutorial, API references, and more.

One of the main reasons for CodeIgniter’s popularity is the clear and concise documentation it provides. Sometimes offering too much documentation can be overwhelming and confusing for users, especially if it’s produced in a chaotic manner.

That’s why, conciseness is of equal importance as completeness.

Who’s Doing it Wrong?

The list would be long, no doubt. But, I don’t want to include examples of poor documentation here, because I don’t want to name and shame anyone personally.

But if you’re read carefully this article it will be pretty easy to recognize such kind of documentation when you see it.

Conclusion

So far we’ve seen that having a great product is not enough for you to succeed, and for your users/customers to be happy.

Providing a great documentation is a crucial step on the path to the success, and this fact should not be underestimated.

Any self-respecting web developer should prove its professionalism by spending some additional time to create and provide a good enough documentation. And I’m deeply convinced that these extra efforts will pay back pretty well in the future.

Frequently Asked Questions (FAQs) about Software Documentation

What are the key elements of good software documentation?

Good software documentation should be clear, concise, and comprehensive. It should include an overview of the software, a detailed description of how it works, and step-by-step instructions for using it. It should also include troubleshooting information and FAQs to help users solve common problems. The documentation should be organized in a logical way, with a table of contents and an index to make it easy to navigate. It should also be regularly updated to reflect changes in the software.

How can I make my software documentation more user-friendly?

To make your software documentation more user-friendly, consider using visuals like screenshots, diagrams, and flowcharts to illustrate complex concepts. Use simple, straightforward language and avoid jargon whenever possible. Break up large blocks of text with headings, subheadings, and bullet points to make it easier to read. Also, consider including a glossary of terms for users who may not be familiar with technical terminology.

What are some common mistakes to avoid when writing software documentation?

Some common mistakes to avoid when writing software documentation include using technical jargon without explaining it, failing to update the documentation when the software changes, and not including enough detail or step-by-step instructions. It’s also important to avoid making assumptions about what the user already knows. Always write from the perspective of someone who is new to the software.

How often should I update my software documentation?

Software documentation should be updated whenever there are significant changes to the software, such as new features or updates. It’s also a good idea to review the documentation periodically to ensure that it’s still accurate and relevant. If users are frequently asking the same questions or encountering the same problems, it may be a sign that the documentation needs to be updated.

What is the role of software documentation in software development?

Software documentation plays a crucial role in software development. It serves as a guide for developers, helping them understand how the software works and how to use it. It also serves as a reference for future development work, helping developers avoid making the same mistakes or reinventing the wheel. Additionally, good documentation can help users get the most out of the software, reducing the need for customer support.

How can I improve the readability of my software documentation?

To improve the readability of your software documentation, use clear, concise language and short sentences. Break up large blocks of text with headings, subheadings, and bullet points. Use visuals like screenshots, diagrams, and flowcharts to illustrate complex concepts. Also, consider using a readability tool to check the readability level of your text and make adjustments as needed.

What are some best practices for writing software documentation?

Some best practices for writing software documentation include starting with an overview of the software, providing detailed step-by-step instructions, using visuals to illustrate complex concepts, and including a troubleshooting section and FAQs. It’s also important to use clear, concise language and to organize the documentation in a logical way.

How can I make my software documentation more engaging?

To make your software documentation more engaging, consider using storytelling techniques, like using real-world examples or case studies. Use visuals like screenshots, diagrams, and flowcharts to make the content more visually appealing. Also, consider using interactive elements like quizzes or interactive diagrams to engage users and help them learn.

What is the importance of software documentation for end users?

For end users, software documentation is a vital resource that helps them understand how to use the software effectively. It provides step-by-step instructions, answers to common questions, and troubleshooting information. Good documentation can reduce the need for customer support and help users get the most out of the software.

How can I ensure that my software documentation is accurate?

To ensure that your software documentation is accurate, it’s important to test the software thoroughly and to follow the instructions in the documentation yourself. It’s also a good idea to have someone else review the documentation for accuracy and clarity. Additionally, make sure to update the documentation whenever there are changes to the software.

Is Your Product’s Documentation Good Enough?