Documentation marketing

During my contributions in the area of documentation it turns out most developers have so much fun while developing new features. In the end they are proud of their new product, but don’t provide documentation for their users. Users can be further developers extending the original product via an API, or the user interacting with the product via a GUI or CLI. Sometimes they promote their new product, e.g. a new feature. They write a Blog post, tweet about it, talk on conferences, and so on. But no one else can inform himself about the features and much more important if he once get interested, how to use the product or feature.

Some projects already have one type of documentation called “release notes”. Everything that is new will be documented beside the whole documentation. That’s better then nothing, but it’s incremental, you have to know that something has changed to look it up. Also you need to know the context around the change. The target audience are your existing users.

But the most important target audience are the users not using your product right now, but that will make a decision whether to use your product in the future. They will take a look at the official documentation.

If you don’t update or provide an understandable, up to date documentation, how should they know about the features? How should they know how to use features and how hard it will be? Of course we have tests nowadays, but that’s not the same. You need much more time to get into tests, that’s why we have documentation.

Documentation is like performance, you should not put it in top, but into your definition of done. It’s mandatory if someone should use your product. And in case of products like TYPO3, it’s the same as with software like Sublime Text. The software itself is not the point while selling, but the ecosystem. And that heavily depends on the documentation. As with no documentation, your ecosystem will develop less.

Examples

In my opinion one reason why Symfony is so widely used is there documentation, same is true for Drupal.

Symfony features there documentation right on the Symfony start page as second navigation item and third item on the page.

../../../_images/symfony.png

Symfony start page with documentation highlighted in red.

Drupal also covers documentation on his Drupal start page as third navigation item and as third item on the page.

../../../_images/drupal.png

Drupal start page with documentation highlighted in red.

So please do yourself, and the world a favour and provide the necessary documentation. The ecosystem is well documented and easy to use, as you can see at my Blog post Workflow for: Read the docs, Sphinx and Plantuml.

Further reading

You might also be interested in Workflow for: Read the docs, Sphinx and Plantuml.

Even if I found this out myself, I’m not the only one with this opinion, check out 5 Reasons your product documentation is a marketing asset by Mashable.