Is Your Product’s Documentation Good Enough?

Ivaylo Gerchev
Typewriter on green lawn

Βethan

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.

  1. 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.

  2. 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.

  3. 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 Documentation

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

Code Igniter documentation

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.

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Guest

    Well stated.

  • Taylor Ren

    Symfony’s documentation is of great quality.

  • Vasi

    Very good! Thanks.

  • Guest

    Great article, but so what are some of the best tools to create great documentations for your products? Or even some of the modules that you develop for your clients?

  • Phil T Tipp

    Great article – well thought out – except:

    “What Components a Good Documentation Consists Of?”

    The grammar and construction of this sub-heading set my teeth on edge. Language is one of the most overlooked aspects of documentation. It must be grammatically correct and where possible, jargon-free – technically explicit where required, yet clear and unambiguous enough to be understood by standard human units who know and care nothing of computer engineering.

    I understand, naturally, that English may well be your second, or third language (kudos if so) – but copy reading for sense and grammar (by a third party) should be an inherent part of the publishing process, especially in the case of educational articles, such as yours, or even more importantly in good documentation, agreed?

    That aside – good solid article, recommended reading – thanks.

  • Ralph Mason

    A much needed article, and one I wish the documenters (if that’s a word) would read.

    One of the big issues I see—even where fairly comprehensive documentation is provided—is that the writers are not clear on who their audience is. As a teacher, I know how important it is to determine where your audience is coming from, what their experience is etc. before starting. Documentation is often written for people with a high level of experience, leaving beginners in the lurch.

    If nothing else, documenters should ask themselves who they are writing for and then make this clear. That is, acknowledge what pre-skills are being assumed, and preferably point to resources for getting up to speed. So often I faithfully follow documentation step by step, only to be brought to the edge of a chasm with no bridge across.

    The other failing of much documentation is that is doesn’t make enough effort to see things from the learner’s point of view, carelessly leaving out critical steps in the process. It’s like leading a blind person along and forgetting to mention the ditch ahead. Try, as much as possible, to clear your mind of what you already know and picture what it would be like to use your product for the first time, without any notion of how it works and what it’s for.

    As the article points out, I often look at new product websites and can’t even work out what the heck the product is for. And each time this happens, a potential customer is lost, as I refuse to persevere.

  • jmueller

    I agree. An addition though:

    > 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.

    It is a good practice to have comments in your source-code. Don’t omit those.
    They are not a replacement for a documentation but they are really helpful if another dev has to take over your source for some reason. Every bit helps

    • Ivaylo Gerchev

      Hi jmueller,

      I don’t say that you must omit all comments in your source files. Comments that explain and clarify the code itself (especially the obscure parts of it), and those that are used by documentation generators are all welcome.

      The comments which I mean are those that tend to serve as a user guide or tutorial about the product. Such comments/instructions must be placed outside of the source files – in separate documentation files.

  • Ivaylo Gerchev

    It seems that some of you guys can’t grasp my point here. You just don’t make difference between API documentation (API reference) and user guide documentation. Your examples are for the former.

    When I say that you shouldn’t use comments as documentation source, I mean documentation in form of user guide, tutorial, and similar instructions. I don’t mean the comments used by the documentation generators.

    So, please, make a difference.