Get Started on the User Documentation

Whether the programmers are responsible for user documentation or not, this phase is the best time to begin producing it. The following documents may have to be written:

User's Guide. This document can be written by the programmers, a technical writer or even the user. Recall that the FS has sections that detail the menus, screens, forms and other user interfaces-do not re-invent the wheel.

A good USER'S GUIDE is divided into sections that represent different users' jobs. In the system USER'S GUIDE, for example, there should be a chapter labeled 'Registrar's Functions', another labeled 'Warehouse Functions' and so forth.

The material should be in the order that the user will normally use it. This makes the USER'S Guide useful for learning the system. Another popular order for USER'S GUIDES is by a logical trace down the tree of menu commands. At the end of the guide provide reference sections where each command, menu, form and message appears in alphabetical order.

Maintenance Guide. How do you get programmers to document the details of their programs for subsequent maintenance? Most find this very difficult to do:

programmers are reluctant to document before the program is written; and good luck getting them to do it after everything else is done. Programmers think that maintainers require a detailed explanation of program logic. This is boring to write and totally unnecessary. There is a simple solution to this: A good, detailed module design specification with structured, self documented code is enough for system maintenance.

The MAINTENANCE GUIDE will consist of the Design Specification, the program listings, and an explanation of how it all fits together, how to approach changes, and how to link and test it all.

Operator's Manager's Guide. This is the equivalent of the USER'S GUIDE for the person who brings the system up in the morning, shuts it down, does backups, handles major problems, does the accounting and so on. The

by the of the hardware and the operating system may be enough-only the procedures unique to the custom software will have to be written down.

Training Documentation. If you will provide courses on how to use the system, plan what form of training material will be required. A good USER'S

should be adequate in most cases. You may have to produce training aids such as overhead transparencies, hands-on exercises, tests and so on.

9.4 PROGRAMMING CASE TOOLS

The following are software products that help the programmer do his or her job better.

These are called CASE (Computer Aided Software Engineering) tools because they help to automate the programming process. See Reference 2.1 for actual products.

9.4 Programming Case Tools The Programming Language

The programming language and compiler is the most important tool. If it is simple and well-suited to the application the programmer will be able to learn it quickly, use the exact construct required, and program without awkward work-arounds, the short comings of the language. The compiler should be fast, and the error messages clear.

Language Sensitive Editor (LSE)

An provides templates for every statement in the language. For example, in PASCAL, the user can type 'FOR' and the produces

FOR :=

'%{statements)%

END;

The programmer merely fills in the variables and the ensures that the syntax is correct. The LSE can also call the compiler. If an error is the compiler, the gets control back, and the programmer is back in the editor-with the compiler error message and the source line that caused it on the screen. The LSE can produce the program header from a template.

An aids in syntax checking, compiling and ensuring consistent source format throughout the system.

Debugger

A debugger helps detect and correct errors. It should provide program stop, trace, and step. A good debugger allows setting and displaying of variables at any point, as well as executing specific parts of a program.

Code Management System (CMS)

Sometimes called a configuration manager, CMS is invaluable for any programming effort. is the 'librarian' that owns all sources. It can police who updates what and ensures that conflicts are avoided if two people are updating the same module at once.

CMS keeps track of all changes to all the modules so that a history of a module is easy to see. And for the icing on the cake, CMS provides easy regression to previous versions of the sources.

can handle anv It is therefore useful not onlv for tracking, source files, but for storing and documentation files, test files, system files as well. Imagine the situation at a manufacturer such as DEC, where there are usually 20 to 30 versions of an operating system supported, each varying slightly depending on hundreds of permutations and combinations of hardware and software flavors. A CMS is absolutely necessary to track all of these versions. (Excuse me for sounding overenthusiastic, but CMS has saved my life many times.)

Chap. 9 The Programming Phase

Module Management System (MMS)

An MMS is used to automate the compile and link process, or the system build. It can rebuild only those components that were changed since the last build. MMS can be used to automatically run a set of tests against a module. MMS is very useful when you are building a 'release' of a system: assembling all the appropriate sources and executable images, as well as all the documentation in a package. MMS works hand-in-hand with CMS where all the sources, document files and command files that run MMS can be stored.

Test Manager

toautomate the testingof use you define a set of tests to be run against the module along with the expected output. will run the tests, and inform the programmer if the results vary from the expected output.

9.5 COPYRIGHTS

The subject of copyrighting software is still in the courts, but a recent ruling states that not only is the piece of software copyrightable, but also the 'look' and 'feel' of it (whatever that means). If you wish to protect your code, add a copyright notice to each source module and document. "Copyright Company Name" is all that is usually required.

9.6 CONCLUSION TO THE PROGRAMMING PHASE Here are some thoughts on programming:

be considered to be an art. Programmers were allowed to "do their own thing." It was very quickly discovered that it is too expensive for that. It has to be considered as a science--rigorously dictated.

Programming is fun--debugging it is not. Watch out for statements such as "Coding is done; all that's left is to debug it, so I am 90% done!" Statistics show that the programmer

is only 50% done after coding.

Here are some thoughts on programmers:

Programmers will always underestimate a task. Teach them pessimism-things will go wrong.

Programmers will enjoy their job if you motivate them with a challenge. Each task should be just a little bit harder or different than the last. If you wish to learn how to motivate programmers, read G. Weinberg's book, "The Psychology of Computer Programming"

(Reference 14).

Programmers are easily abused-they will work overtime when requested. But beware of

9.6 Conclusion to the Programming Phase 109 constant while no extra productivity gained and the programmers will burn out.

At the end of the programming phase look for the

1. The module designs have been walked through and signed off.

2. The individual programs have been coded, tested and signed off by the project leader.

3. The order for the integration has been decided, written in the System Test Plan (and programming is progressing in that order).

4. The responsibility for the user documentation has been assigned, and if you are lucky it has already been started!

QUESTIONS

1. Why do programmers always start codingtoo early (before the completed)? Why is this inadvisable?

2. When does system design breakout stop and module design begin? What factors would override this?

3. Why should programmers plan the module test before writing the code?

4. What is white box and black box testing? Why use both?

five attributes of a structured program.

6. What two things would a good User's Guide be used for? Why provide both?

7. What is the traditional program maintenance document, and why is this disliked? What could replace this?

8. List, in order of importance, six programming Explainwhy you chose the first three as most important.

9. What are the milestones of the Programming Phase?