Tech Biz Writing

It has been estimated that 70 to 80 percent of the cost of developing a new industrial computer system lies with the software. Software overheads, in terms of man-hours per program, remain fairly constant. When it is considered that the mean time for developing a new computer application is about two years, and that bugs affect up to five percent of program lines, it is scarcely surprising that program maintenance is an expensive business. In this process good documentation is imperative.

Computer programmers are notorious for failing properly to document the programs they write. And this is never fully appreciated until there is a need for maintenance, or the operative who wrote it leaves the company bequeathing his eccentric codification to his colleagues. This is an unfortunate tendency because nothing contributes more to reducing the overheads of program maintenance than good documentation.

The software author, or documentalist, should therefore become involved at an early stage. He might sit in with the programming team at the outset — an enlightened procedure now being adopted by some companies — or he may be called in when the program is ready for testing. In the worst case, he/she may be invited to participate when the actual programmer has departed, leaving behind a trail of poorly documented software.

He may be asked to document a single program, or a software system. The difference is that a program performs a unitary function, whereas a system is a set of communicating programs.

The development of a program, or suite of programs, follows much the same lines as any other technical product, including technical documentation:

* Requirement
* Specification
* System design
* Software system design
* Program design
* Implementation
* Integration
* Acceptance testing
* Maintenance &c.

Software documentation embraces the whole field of programming languages, while also taking in the disciplines of technical authorship. It exists in a curious interface between abstract ideas and concrete implementation. It deals with the “intelligence” that makes a machine perform. The “design” deferred.

Good software documentation will probably contain some or all of the following features. Probably because as a fairly recent innovation, no two practitioners will agree on the perfect requirement. The breakdown is only a suggestion therefore, but it should serve to give a distinct impression of what software documentation is all about.

Title page (including any reference numbers)
Contents
Outline of program
Update or amendment record
Program specification:
Mathematical basis
Program description
Limitations and restrictions (as presently known)
Description of input
Description of output
Programming information:
Block diagram
Specimen test data
Program listing
Specimen of output from test data
Record of program development
Operating instructions

Many of those whose job it is to write programs will consider the documentation an irksome chore. There have been moves therefore for some years towards a concept called the self-documenting program. The aim is to use to the full the annotating features of the programming language itself. The programmer then relies almost entirely on the listing for maintenance and other purposes. Unfortunately, like most other attempts at improving software productivity, the concept has not proved as effective as was thought. Full software documentation is still a great asset to future users.

The following breaks down the above description in more detail:

Title page
More than just a title page, it should bear a descriptive title of the program, references (if any), programmer/analyst’s name, or names, and dates of specification and completion.
Contents
List of contents with page numbers.
Outline of program
Brief description of the function of the program, language used, special techniques incorporated, system configuration written for, and utilities or operating system required.
Update record
Reasons for, and dates of any amendments, together with known effects.
Program specification
Mathematical basis Any mathematical techniques used.
Program description General description including loops and procedures.
Limitations and restrictions Restrictions on field size, upper limits on data, and general accuracy.
Description of input Input parameters or data requirements.
Description of output Details of output.

Block diagram A general system diagram — but not a detailed flowchart here (although some documentalists do) because it is almost impossible to amend in line with maintenance changes.
Specimen test data It is not feasible completely to test every loop and procedure in a program, since the variations may be nearly infinite. Test data are used within certain limits, however, and this, plus expected results should be listed at this point.
Program listing A print-out of the program.
Specimen of output from test data Useful for debugging.
Record of program development A log of progress during testing.
Operating instructions
These may appear as a separate user manual, or part of an overall document.

Software and its documentation are developing quickly. New program development tools may even eliminate completely the need for applications programmers in the years ahead– though this has been forecast for more years than many of us would care to remember.

In the present state of the art there is a steady demand for the careful software author. He/she must be a programmer, a writer, and a solver of conundrums. The job is demanding, but the rewards are excellent.

Next: 13. Outline and Design Phase.

This entry was posted on Thursday, May 4th, 2006 at 2:16 pm and is filed under Technical Writing, TechBiz Writing, Educational Textbooks, Software, Documentation. You can follow any responses to this entry through the RSS 2.0 feed. Responses are currently closed, but you can trackback from your own site.