Standard documentation for software systems

By conniey.smith ·
I have been assigned to inventory and create technical documentation for several software systems that have existed for a while. There is some documentation for some of it but I am still trying to determine what's there. Could you please give your input as to what should be included when the "minimun" and/or "standard" documentation is complete. I am interested in knowing what categories are needed (code libraries, kinds of diagrams, user guides?). Thanks for your help.

This conversation is currently closed to new comments.

Thread display: Collapse - | Expand +

All Answers

Collapse -

Databases, classes

by rick In reply to Standard documentation fo ...

I don't envy your job. Documentation is one the most neglected parts of many software projects.

All the databases should be described: tables, columns, datatypes, constraints, E/R diagrams.

All classes should be described: properties and methods.

This might be a good time for listing tasks, as some of these and their parts of the UI can be lost in antiquity or no longer relevant.

If you have access to some sort of case tool or graphic program such as Visio, a picture is very often worth more than a thousand words.

Good luck...

Collapse -

How Good is your English?

by Jalapeno Bob In reply to Standard documentation fo ...

Standard documentation of a software project is a multistep process. I feel it should consist of at least the following documents:
1. Executive summary
2. Top level design
3. Detail Design
4. Implementation and Test
5. User Guide
I know, that sounds like a lot of writing and, to be honest, it can be. Let me describe each, in turn:
1. Executive summary - this document restates and expands upon the goal of the software project. The audience for this is the executive ranks, sales and marketing types and the management levels above your immediate supervisor. This tells everyone exactly what you are trying to build, sell, enhance or what ever, what it does and why it is valuable to your organization. Keep it short, no longer than one or two pages.
2. Top Level Design - This document describes what others need to know about the software. This includes command interface, inputs, outputs, visible classes, external databases created and used, resouces used, relationship to other projects and programs, and so forth.
3. Detail Design - This document describes the pre-implementation design choices made to expand upon the top level design. It normally contains the basic structure for the program, the internal classes and database structures and such. For existing software, pull together what you can.
4. Implementation and Test - This document describes the implementation time assumptions and decisions for the code and test cases for code-level testing. Again, for existing software, pull together what you can.
5. User Guide - This is the most important document. It should be directly derived from the Executive Summary and the Top Level design document. This is the second place where your English skills will be required. You need to tell the user, in terms they can understand and at their reading comprehension level, what this program does for them and how to use it. As a minimum, you need to document the command interface, regardless of whether it is command line or graphical or both. I recommend that you include "case studies" or "scenarios" of common operation.
For example, if your product is a word processor, your scenarios should include how to start and write a short business memo, how to add graphics to a document, how to write and update a multisection business report with section headers and how to create a document template. You should also provide examples of advanced features, such as creating tables of contents, figures, tables, equations and quotations, creating an index and creating a bibliography.

From your statement of work, it sounds like your boss just pointed you to a heap of programs that the company created over they years. If I were you, I would begin with a memo to my boss listing all of the programs to be documented and the documentation structure you plan to use. This will give both of you a good idea of the scope of the project and allows a realistic estimate of the time and other resouces required.
Once my supervisor I agree on the first memo, I would draft a second memo listing the existing documentation that I found. I would ask the current users if they have any manuals, memos, notes or cheat sheets which could be included into the documentation. For any personal notes or cheatsheets, I would acknowledge their contribution in this second memo - it's just good office politics.
When I review this list with my supervisor, I would suggest an priority order for which programs to document first.

I wish you the best of luck. I do not envy your position. Most importantly, since this will be a time consuming and expensive project for your organization, keep open lines of communication with your supervisor and the current users of these programs.

Related Discussions

Related Forums