Good Documentation

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.

Software Documentation

Software Documentation

This is an area of Software Development that has always been a challenge. The documentation falls into 6 general categories:

 

  • Software Design Documentation
  • Software Testing and Test Results
  • Software Implementation Details
  • Software Change Management
  • User Documentation
  • Coding Standards

 

Each of these has its own specific issues.

 

There are formal documentation standards including IEEE 829 for Software Test Documentation and IEEE 830 for Software Requirements Specification and IEEE 1016 for Software Design Description. Even if you are not using these standards, it is worth reading them and understanding the ideas and methods they teach. These are well thought out standards.

 

Software Design Documentation

We work for a wide range of clients and some have very strict criteria while others leave it entirely up to us. The strictest criteria we work with are biomedical, automotive or transport clients. These require upfront definitions of everything including the Software Test Methodology and the specific tests to be done and the pass fail criteria. And of course, every change request up-issues every affected document. So that has to be budgeted for.

 

Software Design balances the project priorities

Software Design

For clients without specific requirements, we use the following methods:

 

  • Define the requirements and how they will be tested
  • State all known constraints
  • Describe the operating system
  • Show the Functional Decomposition into modules
  • Show the module communication
  • Use diagrams to show all State Machines
  • Document tests and test results

 

For larger projects, we might choose to have separate requirements and test documents but we always align the numbering so the test for a requirement has the same number as the requirement. For instance, if requirement 2.3.1 was that the system accommodate BAUD rates from 9600 to 115200, then test 2.3.1 would be to set and confirm the system operated with each of the BAUD rates.

 

This helps with both ensuring requirements are all tested and implemented, and that changes can easily identify which tests need review when a requirement is changed. Very large projects would use a Requirements Allocation Matrix where the requirement is cross-referenced with the modules that implement it.

 

Functional Decomposition

Functional Decomposition is the process of breaking the project up into specific modules and allocating requirements and functions to them. Since we do the whole gamut of Electronics Design and Embedded Software Development, this includes deciding how many processors we will use and how we break up requirements between them.

 

Functional Decomposition

Functional Decomposition

The intent is to take the complex and break it down into simpler pieces until they are simple enough to implement as functions in their own right.

 

Software Testing

For Software Testing the process is conceptually simple:

 

  • What is tested – which requirement are we meeting
  • How is it tested – the test protocol
  • What results are recorded – the test records
  • What the pass criteria is – the test acceptance criteria

 

This is usually best handled with tables except for user interface interactions which might use recordings as well as written test results documentation.

 

Software Implementation Details

This usually consists of the source code documentation since the Software Design has already been documented. Many modern toolsets include source browsing and database tools, but these require the end client to have the same toolsets. So we also add Source Code Documentation tags supported by Doxygen which allows a toolset and platform independent set of documentation to be created. If you haven’t used it, what you get is a website with everything hyperlinked. You can also create hyperlinked PDFs but we usually stay with the html.

 

Doxygen Source Code Documentation

Doxygen

You can create diagrams, caller graphs, callee graphs and state machine descriptions using the Graphviz tool which is supported by Doxygen.

 

Doxygen Call Graph

Doxygen Call Graph

Our gratitude goes to Dimitri Van Heesch for creating and maintaining Doxygen which you can support by donation.

 

Software Change Management

So you have a software project that passes all its tests and its out there and working. Now you, or your client, want to change something!

 

The last thing we want to do is break something while trying to make it better. So when changes are needed, they have to be analysed. Things to consider are:

 

  • Which requirements are affected by the change?
  • How risky is the change?
  • Who need to approve of the change?
  • Are there any new requirements or new tests required?
  • Will field testing be necessary?
  • Are there regulatory approvals affected?

 

So trivial changes like updating the wording on a form are usually low risk and don’t require a lot of risk management of multiple levels of signoff.

 

A more significant change like altering the wheel pressure balancing algorithm in a ABS braking system gets the maximum level of attention.

 

User Documentation

If the product has a User Interface or supports user interaction, then this also needs to be documented. This documentation is usually written for the user to read and is intended to assist the user.

 

The format of the documentation depends on the product. It could be online help, tool tips, printed manual, soft manual, on screen or printed on the product itself. One method of User Documentation assessment is with randomly selected people who could be potential users. This is to identify concepts understood by the development team by not either generally understood or else not adequately explained in the documentation.

 

Coding Standards

This will be covered in more detail in another blog post. Because a range of programmers will work on any significant project, it is well worth defining how code is to be written. This consistency will lead to easier to read and maintain code.

 

For instance, Embedded C bracketing uses to follow the UNIX convention which goes like this:

 

for(length = MIN; length <= MAX; length++){
do_some_stuff();}
next_lot_of_stuff_to_do();

 

This had advantages in the days when VDU screen space and Teletype or Lineprinter paper space was at a premium, but it makes sense to make the indenting easier to understand by doing it this way:

 

for(length = MIN; length <= MAX; length++)
{
do_some_stuff();
}
next_lot_of_stuff_to_do();

 

Regardless of the type of project, easy to read and understand Software Documentation will reduce maintenance costs is essential for larger teams to be able to deliver a working project.

 

Successful Endeavours specialise in Electronics Design and Embedded Software Development. Ray Keefe has developed market leading electronics products in Australia for nearly 30 years. This post is Copyright © 2012 Successful Endeavours Pty Ltd