Re: Should software documenters learn to read code?

Subject: Re: Should software documenters learn to read code?
From: Stuart Burnfield <slb -at- westnet -dot- com -dot- au>
To: Techwr-l <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 13 Feb 2009 14:06:36 +0900 (WST)

Peter's example (the "-g" flag that had changed to "-w") is a good one. This sort of change is often overlooked and is relatively easy to spot in the code. Sometimes you don't even have to know the language - the header or comments will list the main options or flags.

Just yesterday I was looking for messages and codes that have been added recently. There's a table of all the messages that are called from elsewhere in the code, but the descriptions can be pretty short and cryptic. I search for where the message number is called in the source code. I can usually tell from the few lines leading up to it what situation would cause the message to be displayed, which helps me draft an explanation to go in the Messages reference.

I wouldn't rely on my own interpretation of the code, and I wouldn't spend hours trying to puzzle something out. But if I need to go to a developer with questions, I want them to be smart, well-informed questions. It's always easier if you manage to work out at least some of the answer yourself. Being able to read code, even if only at a basic level, can help with that.

ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals.

Help & Manual 5: The complete help authoring tool for individual
authors and teams. Professional power, intuitive interface. Write
once, publish to 8 formats. Multi-user authoring and version control!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:

Previous by Author: RE: Editing .ico files
Next by Author: Re: The plot thickens - re: "fraudster"
Previous by Thread: RE: Should software documenters learn to read code?
Next by Thread: Re: Should software documenters learn to read code?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads