Good Documentation

Good Documentation makes it possible for other people to leverage work already done. It can be the difference between something being usable and it being scrapped or ignored. We have already looked at some aspects of how Software Documentation can be created. An example being shown below.

Doxygen Call Graph

This is only one form of documentation. To use a Software Module you will want the API definition. Here is an example in Doxygen format of a readily usable interface. Not much mystery here. Note that the hyperlinks have been removed to stop is using links you can’t access. Normally every definition is hyperlinked so you can go right to it.

So it should prove straight forward to use a module documented like this. Of course I’ve picked a simple example.

O’Reilly recently published a great article on this and so I’m going to summarise here and you can check out the full article for the rest of the details.

• Write documentation that is inviting and clear
• Write documentation that is comprehensive, detailing all aspects of the project
• Write documentation that is skimmable
• Write documentation that offers examples of how to use the software
• Write documentation that has repetition, when useful
• Write documentation that is maintained and up to date
• Write documentation that is easy to contribute to
• Write documentation that is easy to find

Seems perfectly sensible to me. If you want you software to be reused, make it as inviting as possible for subsequent developers to be able to engage with, understand, and quickly leverage what you have already done.

You can read the complete article at the eight rules of good documentation.

Successful Endeavours specialise in Electronics Design and Embedded Software Development, focusing on products that are intended to be Made In Australia. Ray Keefe has developed market leading electronics products in Australia for more than 30 years. This post is Copyright © 2018 Successful Endeavours Pty Ltd.