Meet the new DeskMetrics’ documentation and get some tips on writing yours!

Documentation often determines if a project will be used or kept in the attic forever. You can have the best product out there, but it might fall flat because of a lack of good documentation.

At DeskMetrics, we realized that our documentation hasn’t been as helpful to our users as we wanted. So we decided to review it and make some improvements in order to make our integration easier. It wasn’t an easy essay but it worth! The new documentation is much better and we have learned a lot during the improvement process!

So to help other developers that may be in the same situation, here are the most important things we realized a documentation must have:

1) Visibility

Our documentation was hidden inside our support forum and people couldn’t easily find it. In this way, users would sign up an account but take a long time to integrate or sometimes never integrate because they needed to look for it. To solve this problem, we now place our documentation in an exclusive subdomain: http://docs.deskmetrics.com/. We also developed a wizard toll that tells users what to do since the moment they sign up an account until the moment they finish integration and can start using our analytics. With this tool, users get to know where they can find everything they need, including the documentation. This certainly helps a lot!

So remember that if your users must find some information, it needs to be extremely easy to find. They must not need to look for it!

2) Easiness to read and undestand

DeskMetrics’ documentation was written into TenderApp knowledge base, which had no syntax highlighting support. We first decided to use this application in order to make things simpler, since our support was also developed using TenderApp. But after some time, we realized it was a little bit confusing to our users since there were a lot of codes without difference between each other. Users couldn’t easily find the keywords inside the code and they used to get lost.

So to write our new documentation we decided to use Sphinx, the same tool used by Django and Python. This application has features as syntax highlighting, serverless search and it also has the ability to export to multiple formats. In this way, our new documentation provides an easier access to documentation and to different information within the code.

So have in mind that when deciding which tool you will use to write your software’s documentation, it should be a tool that makes the output documentation easy to read!

3) Frequent updates

As developers are always making improvements on software and they must update them, it’s very important to write your documentation by using a tool that makes this job simpler and easier. In this way, improvements will go faster to the users’ hand!

So what also influenced our decision to choose Sphinx to write our new documentation is that it has built-in templates, a great output and it is written in versionable format (reStructuredText). These tools allow us to easily write documentation like Python and Django do and almost “make developers want to write documentation”.

We also have an automated deployment solution based on git which does almost all work on publishing our documentation. We only do a “git push” to our servers in order to have the newest documentation online, in a 5 second process. That’s pretty quick, don’t you think?

So remember that your documentation must be easy to read, easy to write and easy to deploy!

4) User feedback

In order to maintain a close relationship to our users/readers, on the new DeskMetrics’ documentation we’re using Disqus’ comment system. This tool allows us to provide a better support to our users since they can send us their doubts or questions at the same time they are reading our documentation and on the same page it is.

It’s very important to give users the chance to ask questions or give their impressions. You help people use your software, show users you’re there for them and receive feedback that will probably help you improving your software.

Quick Tip

After getting to know all the things we’ve learned and improved, check out the new DeskMetrics’ documentation! If you have any doubts or comments on how to improve it, please let us know! If you want to contribute to our new documentation, fork it at Github.