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 second Deb's experience. I can answer questions for myself about how
the code works, without bothering developers with trivial questions,
saving my precious interactions with them for the tricky stuff. It
also helps my credibility with them and earns respect, something that
many tech writers complain about not getting.
Suppose I want to know what the constraints are on an input field,
such as a password (e.g., length limits, whether spaces or punctuation
characters are accepted), because I want to give guidance beyond just
"enter your password in the password field". I can:
* ask a developer (uses up their time)
* try a bunch of combinations and hope I've hit all the corner cases
(uses up my time)
* look at the code and see what the field accepts (not an option for
the code-illiterate writer)
Thinking that learning to read code would make me stop thinking about
users is like thinking that learning Spanish would make me stop
speaking English. If I switched my career to programming, that might
happen eventually, but as long as I'm a technical writer, I'm going to
have a user orientation.
> Reading code is also a great item to have on your resume.
Yes, and why is that? Because it shows that you are capable of
understanding something *technical*! It also expands the range of
types of documentation you can work on to include developer-oriented
documentation (SDKs, etc.). Note that even in developer documentation,
the writer needs a "user" orientation; the needs of programmers using
an API are different from those of the programmers who wrote the API.
It is entirely possible to do both.
On Fri, Feb 13, 2009 at 5:54 AM, Deb McNally <tig -dot- techwriter -at- gmail -dot- com> wrote:
> I would have to disagree. I have been able to read (and write) code
> for years. It definitely didn't change the way I think. What it did do
> is make it so that I am able to understand what the programmers are
> saying when they get stuck in 'programmer speak'. This has made me an
> asset to the companies I have worked for because I can interpret and
> explain to others.
>
> Reading code is also a great item to have on your resume.
>
> Deb
> Sent from my iPhone
>
> On Feb 12, 2009, at 10:03 AM, "Downing, David"
> <DavidDowning -at- users -dot- com> wrote:
>
>> Should technical writers who do software documentation -- which is
>> most
>> of us -- learn to read the actual code of the software they're
>> documentation? Of course, on general principles, the more you know the
>> better. And if you learned the programming language on your own time,
>> the question of whether you should be spending your on-the-clock time
>> doing so wouldn't be an issue.
>>
>> But there is a danger. One reason programmers tend to make bad
>> documenters is that they think in terms of the mechanics of the
>> program,
>> rather than in terms of the tasks the end user needs to perform. I
>> technical writer who starts reading code might start thinking this way
>> as well.
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-
