BD Tech Concepts llc

Software-Related Documentation
User’s Manual and Source-Code Documentation


Figure 6: Lwarp Manual — Sample Diagram

Figure 6 is an excerpt from the Lwarp v0.32 Manual (1.3 MB pdf). This manual is a combined user’s manual and source-code documentation, an example of “literate programming”.

For more information, see -HTML5 Generation — lwarp package.

Operating Procedures
Test procedures

Each time software is changed, it should be validated for proper operation before being released for general use. This important function must be carefully thought out. A thorough test procedure will test each software function, including all hardware interfaces plus associated noise and error handling conditions, and the proper software response to each possible input given each possible current state.

State machines

It is useful to create a state machine including every possible combination of input, output, and software state. The creation of this state machine can, in itself, reveal design flaws or force decisions about combinations which nobody had thought of before.

The state machine, if created and incorporated into the initial design process, can be used as a guide for the software engineers to ensure that they have a complete description of the correct action of the program.

When described in graphical format, the state machine makes a valuable part of the software test procedure, describing in an easy-to-use visual format the correct operation of the program.

When converted to a table format, the state machine may be implemented in software, resulting in an easily maintained piece of code, readily adaptable to design changes or future product versions. A software state machine also avoids the nightmare of large blocks of heavily nested conditional code and its associated mysterious functional glitches.

Design reviews

During the process of creating a state machine to describe a piece of software, certain functional and user-interface design improvements can become evident, especially in embedded software with minimal front-panel interfaces, resulting in a cleaner and easier-to-use product.

Universal icons instead of English-language text, consistent state-transition actions, simpler key combinations and editing methods, more meaningful visual and audible feedback, unplanned special-case situations, error handling, and in some cases a reduction in the total number of keys or feedback LEDs — all are possible improvements from a full design review.

Even something as simple as a change of the icon on a key’s label can make it more obvious what that key does — such as converting a right arrow into a curved clockwise arrow to illustrate that the key causes something to rotate, or using a small arrow icon for a key which produces smaller changes, and a larger arrow icon for a key which produces larger changes.