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.
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.
A 32 bit Pseudo Random Number Generator which passes the Die Hard test suite for randomness. It also provides 8 and 16 bit random numbers and a complex seed arrangement.
get the next U16 value in the random number sequence
get the next U32 value in the random number sequence
get the next U8 value in the random number sequence
use the seed values to churn the seed as much as you can
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.