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

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.

Module MS_RNG

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.

Functions
void MS_RNG_Seed (U32_t seed1, U32_t seed2)
use the seed values to churn the seed as much as you can
U32_t MS_RNG_Get_U32 (void)
get the next U32 value in the random number sequence
U16_t MS_RNG_Get_U16 (void)
get the next U16 value in the random number sequence
U8_t MS_RNG_Get_U8 (void)
get the next U8 value in the random number sequence

Function Documentation

U16_t MS_RNG_Get_U16 ( void  )

get the next U16 value in the random number sequence
Returns U16 random number

 

  U32_t MS_RNG_Get_U32 ( void  )

get the next U32 value in the random number sequence
Returns U32 random number

 

U8_t MS_RNG_Get_U8 ( void  )

get the next U8 value in the random number sequence
Returns U8 random number

 

void MS_RNG_Seed ( U32_t  seed1,
U32_t  seed2 
)

use the seed values to churn the seed as much as you can

Parameters

seed1 = first seed component
seed2 = second seed component

Returns void

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 AustraliaRay Keefe has developed market leading electronics products in Australia for more than 30 years. This post is Copyright © 2018 Successful Endeavours Pty Ltd.