alright, you're looking for system documentation, then. I'll see what I can remember from my days of writing it and might add more if I miss anything major. But the basic idea:
1) You're not looking to document the obvious - so you don't want to get too specific. You don't want anything too language specific either. Basically you are NOT necessarily documenting the logic of each program - if I can get the idea of something from looking at the program, then it's not worth documenting. You're looking to document the not-so-obvious in a way that any programmer will understand the system.
Example items to definitely document:
2) Data flows: How does data enter and exit the system? Does it come in from a file, terminal, etc? What path does it take to an exit (printer, file, offsite processor)? Which programs touch the data and in what ways do they touch it (input, processing, reporting?)?
3) Data descriptions: What does each field represent, in terms that are language neutral? In other words, what does the data field mean and how do I access it (again language neutral)? If it has some kind of code numbering, define all the codes and what they represent.
4) Workflow processing: Again in language neutral terms, what am I doing to the data at each step? What is the process involved in reporting the data at each step? This is as close to direct program documentation you will get in most cases, but again we want the non-obvious, not what can easily be figured out. Program 1 does A, B & C; Program 2 does E, F, and G, etc.
5) Program dependencies: What programs get called by other programs (DLLs, widely used in-house OBJects & LIBraries, standard utilities)? What data files are required at each step? What other resources are required for the program to work correctly (DB up and running, DB IDs, certain user ids, certain permissions, web server in the case of web apps, runtimes in the case of interpreted languages)?
This basically your system trouble-shooting section - your external requirements so the programs run properly.
6) Detail documentation: This is where you would document the specific program processes that would NOT be clear upon inspection of the program. You would not document specifically each step, but the things that are overly complex in logic (example: I did a couple of data-driven logic programs which required thorough documentation of logic because the function was not obvious to others) or requirements (example: edit checks on data). This should be very minimal in most cases.
Hope this helps you some.
