BD Tech Concepts LLC
Software-Related Documentation
User’s Manual and Source-Code Documentation
Figure 6 is an excerpt from a prior version of the Lwarp v0.902 Manual (2.5 MB PDF). This manual is a combined user’s manual and source-code documentation, an example of “literate programming”.
For more information, see LaTeX to HTML Converter — The Lwarp package.
Operating Procedures
-
• Elaborate software operating procedures benefit from the inclusion of additional diagrams to help explain the logical connections of the various functions and processes which are involved. Typesetting is used to indicate user-interface functions, and screen images are used to highlight important selections.
-
– Sample: How to set up sales-tax handling in the SQL-Ledger® double-entry accounting system:
SQL-Ledger — Handling Sales Taxes — PDF
Figure 7 demonstrates a conceptual-logic diagram, showing the relationship between the various legislated sales-taxes, their software accounts, their software tax-rate settings. Also shown is how several at a time may be selected/deselected for a particular customer/vendor account, and also for a collection of parts/services on a particular invoice. The flowing arrows show the application of individual sales taxes through the various accounts and selections for each individual item on the invoice.
-
-
• Diagrams are also used to illustrate the changing state of the system as a the user progresses through the required operations. Typesetting is used to highlight user-entry typing, display, warnings and notes.
-
– Sample: How to move the Debian operating system to a new harddrive:
Moving Debian “Wheezy” and grub2 to a New Drive — PDF
Copying an entire operating system to a new harddrive can involve several steps, during which entire groups of directories are added and removed at different times. Figure 8 is one of several which help the user keep track of what is going where during the transfer process.
-
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.
-
• Sample: Software test procedure:
Fryer — Software Test Procedure — PDF
Illustrated in the PDF and in Figure 9 are:
-
– an overview of the product,
-
– the use of a state machine in tabular form (also see Figure 10 for the same information in diagram form,)
-
– statements of specification,
-
– a checklist for each state’s actions,
-
– additional tests to perform where necessary,
-
– ESD noise and power-loss recovery testing, and
-
– typeset user-interface buttons and displays.
-
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.
-
• Sample: State machines and user-interface:
Fryer — Final Operating Specification — PDF
A sample state machine in diagram form is in Figure 10. States are in shown in green, machine actions in red, and movement to/from other states is in blue. Key icons or text show the user-initiated or other actions required to move to another state. The same information may be presented in tabular form, as shown previously in Figure 9.
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.