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.
> I have an interesting question up my sleeve. Recently, I have been
> given the responsibility of documenting source code written
> in C. The document should
> describe entity relationships and many more associated with
> source codes.
> Can anyone point me to a ready reckoner that describes "do's
> and don'ts"
> on creating such documentation.
All I can say (and I have programmed in the past, still do a little) is to
keep the reader in mind. This isn't user documentation. Or is it? I've
encountered software libraries where the target user is another programmer
who will plug the component into a larger application, but where the only
documentation was the source code. Bad idea in my opinion, but I've seen it
done.
You do read code and program a little, don't you?
...
> This is the description of a signal and it is as below:
>
> "The PERR# pin is sustained tri-state and is driven active by
> the agent receiving
> data two clocks following the data when a data parity error
> is detected."
>
> Is there any way that this can be made readable and simpler?
> Are there any style
> guides avaiable whilst documenting such information? There
> are many such instances
> and surprisingly these are part of the IEEE specifications.
Unfortunately, technical descriptions like that tend to require the hard
terminology and passive construction. There may not be much you can do to
improve it, particularly if you are working on a small subset of a large
collection of descriptions.
I would suggest that the sentence is a run-on, though, and replace the "and"
with a period. I would also be tempted (if I were working on the whole set)
to see if there is a way to use a table, showing the potential states of the
pin and the inputs that put the pin in each state. As a programmer, I always
appreciated that kind of information in a tabular format.
