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.
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. http://www.doctohelp.com
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! http://www.helpandmanual.com/
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
