Sat, Apr 28, 2001

Our major final deliverable documents, and the normal basic functions are as follows. In brackets I include what it would be used for after the delivery of your product.

1. Contract: the final requirements--what the software should do, not how it should do it; [Mostly of historical interest for our projects at this point.]

2. Implementation Manual: how the software actually implemented the requirements (1 above)--the software design/architecture that implemented the requirements, with class/function names, variables, etc. This is the "as built" plans for the software. [This would be studied--and eventually modified--by someone who wants to update the software to learn about the classes, what/how data is passed around, what major tasks are done, where pieces logically appear in the overall architecture, etc. This has no linkage to the computer the software is installed on--someone could take this document to the library or sit under a tree and study it to decide what they want to change in the architecture.]

3. Maintenance Manual: a mapping of the implementation (2 above) to actual files, directories, libraries, etc., and instructions/procedures for actually doing the software changes arrived at while studying the implementation (2 above). This might include a table that maps class/function names from the Implementation Manual to actual file names and directories, the locations of the files, etc. It would include instructions (for example) on how to check out the source code, compile it, test it, how to gracefully shut down a server and re-start it, etc. [This would be used by someone actually sitting at the computer when they are ready to actually code the changes they decided upon while looking at the Implementation manual in 2 above. It would tell them were to look for files, how to compile, how to stop and start the server, etc.]

4. User Manual: a guide to the end user, with both the overall scope/context of the system as well as details on what the buttons, menus, etc. do. [This would be read by someone who either has never used the system, or someone who wants a further understanding of some features. This manual could be taken away and read in isolation (library, under a tree) to prepare to use it, and it would probably be sitting next to the person at the computer when they are using the software, to step through examples, compare figures with their screen, look things up, etc.]

With respect to the Implementation and Maintenance manuals, note that just like the Requirements Spec says nothing about how the software should be implemented, only what it should do, the Implementation should (generally, not always) say nothing about the actual files on disk, where they are located/arranged, who includes whom, etc., only what the logical code structure is, with real/final class names, etc. (Keep in mind, you can have many classes/functions in a single disk file, and the class and file names might be very different from each other.)

In the most general case there would be no duplication of material between the Implementation, Maintenance, and User manuals. In practice there might be a little duplication (common sense), but the best thing to do is to use cross references between the manuals wherever possible, and make the manuals otherwise distinct. If you succeed at effectively cross-referencing between the manuals you will save someone who picks up the wrong manual, or wants to understand something specific that is not covered in the manual they are in. You will also save yourself pain and trouble, as well as anyone who maintains the documents in the future. (Imagine having to maintain similar prose in multiple places - ugh.) For example, in your Implementation manual you might have (as I mentioned above) a table mapping class/function names to actual file names. Here you might have a footnote or parenthetical statement that refers the reader to the Implementation manual to learn more about the classes/functions. Also this is a good thing to keep in mind when you write the preface to the document as we have done in the past. Something like "This document is intended to describe the software architecture..." not the realization in terms of files on the disk, etc. We have done this in each of the documents already. Answering "Who is the intended reader, what is their presumed skill level/expertise,..." etc. Both the Preface statements and the cross references serve to link the documents while still distinguishing their respective roles.

If still unsure where a particular thing belongs, try asking yourself "Does this deal with editing the code, compiling, building, delivering, installing, etc.?" If so, it probably belongs in the Maintenance Manual. If not, ask yourself "Is this something a user would need/want to understand while using the software?" If so, it probably belongs in the User Manual. If not, ask yourself "Is this something related to the software architecture, the classes, function names, etc.?" If so, it probably belongs in the Implementation Manual.

Hope that all helps and not confuses.

BTW, here is a link to my slides from the day in class when we went over the final package contents, etc.