Ok the time has come to standardize documentation for projects at work. Here is what I am proposing (for intranet web-apps). Any suggestions, comments, criticism, etc, would be greatly appreciated. 1. User Manual: Any person with basic computer skills should
be able to use the system after reading the manual, with a very high-livel understanding of how the system works. ---A. Document walk-through of system following logical user progression. ---B. "What-To-Do" notices in case of an emergency (i.e. "What-To-Do:
If the system fails"). 2. External Documentation of Every File: Any user with basic programming experience should be able to gain a mid-level understanding of how the system from this section. Section should be laid out in intuitive mannor matching folder
structure with each of the following listed for each file. ---A. Purpose ---B. How does the file work? ---C. What files does the file depend on? ---D. What files depend on the file? 3. Internal Documentation of Every File: Meant for developer use only to understand
the system at the lowest level (code level). ---A. Flower box on top of each file containing: -----i. File Name -----ii. Location of File -----iii. Purpose -----iv. Date Create -----v. Date Last Modified ---B. In-line documentation: Each line of code not easily
understandable should be commented before or at the end of the line of code. 4. Calculation Documentation (section only needed if project contains calculations): ---A. Where are calculations done? ---B. How are values calculated? Thanks, riddelrp
I would rip out 2.b out of that line up, and change it to "Level of necessity of this file", and give it a range. For 3. I'd add "Developer(s) that worked with each file" so you know who to turn to for reference if it's necessary. and for your 3.B make it specific
as to where to comment the code. Furthermore, any line that's not obvious to a mid level developer should be commented. 4. Where are the calcuations done is redundant to 3.a But yes, a list of where each value is derived is definitely needed. There's some
more things, and my way is very particular, so you can put it down all you want, not use it, use it, or just expand on it. I like how you're trying, but don't set anything in stone until you make a few application documenation batches. Good Luck, and Happy
Programming.
Thank you for your reply. I think I'll use a few of your suggestions. And I wouldn't set anything in stone before we see how it hashes out the first time at least. Also, for clarification: There are excel files which contain formulas. This is what I was talking
about with part 4. The rest of the calculations (in code files) could indead be located in 3.a. Thanks for your help, riddelrp
riddelrp
Participant
874 Points
175 Posts
Documentation Standards
Aug 27, 2003 02:59 PM|LINK
KraGiE
Star
14567 Points
2926 Posts
Re: Documentation Standards
Aug 27, 2003 05:09 PM|LINK
riddelrp
Participant
874 Points
175 Posts
Re: Documentation Standards
Aug 28, 2003 06:16 PM|LINK