TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
<ludicrous advice meant to make a serious point>Start over, writing the
documentation including comments first. </ludicrous advice meant to make
a serious point>
Coding a software solution should come *after*:
1. A description of the real-world problem in plain language.
2. Requirements.
3. Design and architecture.
To be more helpful however, usually code documentation consists of names
and descriptions. In the VB/Java environment you specified, you will
probably want to start by commenting classes, objects, functions, and
routines. After those descriptions are clear, describe the attributes,
variables, properties, methods, subroutines, and events.
The question of where you and the programmers write is mostly a
maintenance issue. However, the literature on Software Development
Process recommends providing documentation outside the code because it's
easier to understand that way.
Code documentation is only a step into the ballroom of process maturity.
You may want to subscribe to magazines such as Software Development
which include lots of advice. In addition to the templates I sent you
earlier, here is a bibliography of some of the Software Development
Process literature:
Booch, Grady. 1996. Object Solutions: Managing the Object-Oriented
Project. Reading, Ms: Addison-Wesley.
Carnegie Melon University, Software Engineering Institute. 1995. The
Capability Maturity Model: Guidelines for Improving the Software
Process. Reading, Massachusetts: Addison Wesley.
Fowler, Martin. 1997. UML Distilled: Applying the Standard Object
Modeling Language. Reading, Ms: Addison Wesley.
Humphrey, Watts S. 1997. Introductin to the Personal Software Process.
Reading, Ms: Addison-Wesley
Kit, Edward. 1995. Software Testing in the Real World. Reading, Ms:
Addison Wesley.
Larman, Craig. 1998. Applying UML and Patterns: An Intorduction to
Object-Oriented Analysis and Design. Upper Saddle River, NJ: Prentice
Hall PTR
Maguire, Steve. 1994. Debugging the Development Process. Redmond, Wa:
Microsoft Press.
McCarthy, Jim. 1995. Dynamics of Software Development. Redmond, Wa:
Microsoft Press.
McConnell, Steve. 1993. Code Complete: A Practical Handbook of Software
Construction. Redmond, Washington: Microsoft Press. Effective techniques
in data processing.
McConnell, Steve. 1996. Rapid Development: Taming Wild Software
Schedules. Redmond, Washington: Microsoft Press. Models of software
development.
Perry, William. 1995. Effective Methods for Software Testing. New York,
NY: John Wiley & Sons.
Wiegers, Karl E. 1996. Creating a Software Engineering Culture. New
York, NY: Dorset House Publishing.
Yourdon, Edward. 1996. Rise & Resurrection of the American Programmer.
Upper Saddel River, NJ: Yourdon Press.
Jason R. Huntington
Senior Technical Writer
Captura Software, Inc.
-----Original Message-----
From: Tracey Moore [SMTP:traceym -at- APPLIEDMAPPING -dot- COM]
Sent: Tuesday, November 03, 1998 11:46 AM
To: TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
Subject: Code Documentation
My company has recently completed a visual basic/java
application and we =
now need to document the code. (All we've done so far is print
out the =
code itself.) Does anyone out there have experience with this?
How do you document? What should the document look like? Any
suggestions =
on resources for sample documents?
As you can see, we're babies (uh, make that embryos) at doing
this. =
Thanks in advance for your help.
