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.
At 12:03 PM 04/11/2001 +0530, SATISH RAJ H wrote:
>My organization requires me to do source code documen-
>tation in Delphi...What I need is methodologies/strategies
>Till date, I am used to doing end user documentation.
>Source code documentation, (I feel!) is a different cup of tea
> Not sure how to go about with it. A few tips would be great
Although I have not yet used Delphi, I have documented a ton of source code
over the years, so I hope that the following will help you.
The main difference is that of your target audience. Whereas some of your
novice users may be barely unable to distinguish between a monitor and a
keyboard (don't laugh; a colleague once had a user complain that his system
was lousy and it was all his fault ... "I kept pressing the [HELP] key, but
you never came!"), source code documentation is written for developers, who
will understand basic programming tenets, such terms as algorithms, etc.
However, your reader may not be familiar with that particular software
language ... Most experienced developers/programmers can relate horror
stories about garbage they inherited and were expected to repair or
enhance, despite the fact that there were no manuals or third party books
available (and, before the internet, you couldn't even track them down) in
languages they'd never heard of before.
Another difference is that source code documentation is usually
incorporated into the code, rather than presented as a separate document or
booklet. Every language has at least one character which the code ignores,
and which is thus used for comments/documentation. Since the main function
of source code documentation is to enable a developer to modify a procedure
(or to use it as a template), this will dramatically expedite matters for
him or her.
When I document my code, I just try to make it clear -- both to me (in case
I have to change or correct it) and to any successor who may have to do so.
(The latter obviously requires more detail, since s/he would have no way of
knowing what I was thinking of.)
The main thing to remember is that you have to make it clear to someone who
may have to modify it several years from now, and who won't have a clue
what you did, or why you did it. S/he will have to know the
purpose/function of each segment, a description of each variable or array, etc.
If you're writing the code yourself, I would strongly suggest using
standardized naming conventions. There are many books available which
describe this -- but, the main point is to be clear and consistent. For
example, a variable named ThisMonthNum would be understandable (i.e., 04
for April) even if it doesn't follow any standardized
convention. Conversely, a variable of A1 would be unclear to virtually
anybody (and, yes, some programmers code their work in that manner -- sans
documentation -- to make themselves appear indispensable). If that is not
an option, at least try to be consistent, and define anything that won't be
self-explanatory.
I don't have a generic sample in front of me (although I think I included
this as part of a Borland conference presentation several years ago, so can
probably dig out a sample if you need it). I will also E-Mail you an
actual sample of documented source code (much too long to attach). Feel
free to E-Mail me if I can be of any further help.
However, off the top of my head (and assuming that ' prefaces anything that
the code will ignore):
''********************************************
MY LATEST PROC (proc name)
'Purpose of proc ...
'Variables declared (list each one, alone with its function, whether or not
it is global, etc.
'Arrays declared (same as above)
'*********************************************
Proc MyProc
(MyParameter1, 'function of this parameter
MyParameter2) 'function of this parameter
'-------------------------------------
'Define such-and-such
'-------------------------------------
jklfkladdkl
akaklaljk
'------------------------------------
'Print results
'------------------------------------
kldkldskld
alkl;akdfjkl
EndProc
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
Sponsored by DigiPub Solutions Corp, producers of PDF 2001 Conference East,
June 4-6, Baltimore, MD. Now covering Acrobat 5. Early registration deadline
April 27. http://www.pdfconference.com.
---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.