Software Documentation

This is an area of Software Development that has always been a challenge. The documentation falls into six 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.

 

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.

 

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 hyper-linked. You can also create hyper-linked PDFs but we usually stay with the html.

 

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

 

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