Re: Should software documenters learn to read code?

["Michael West" <mbwest -at- bigpond -dot- com>]

>Should technical writers who do software documentation -- which is most
>of us -- learn to read the actual code of the software they're
>documentation? 


It all depends on whether you're really doing what you wrote; that is
"documenting software." If you're "documenting software" (whatever that
means) then I suppose it might be useful to learn the code.

But if you're doing what I suspect most of us are actually paid to do, that
is, to help users learn how to USE the software to get work done, then I
don't see much use in learning code. 

Usually there are developers around who can answer questions about how the
program behaves in odd situations, if you can't tell by simple observation.
If you have no other source of information about how the software works then
you're screwed, I guess. You gotta do what you gotta do. 

But in the majority of cases I'd place a much higher priority on getting to
know your users and asking them what kinds of information are most useful to
them, and in getting to know how the software actually works from the
end-user's perspective. You need to do what they do in order to discover
what they need to know. And you can spend any extra time left over learning
to write English clearly and concisely. That's a lifetime study. Or learning
about graphics and publication design.

If "software" needs to be "documented", my advice is to let tekkies do it.
Let tech writers help users.  

--
Mike West


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


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
http://www.techwr-l.com/ for more resources and info. 

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat