Re: Should software documenters learn to read code?

Subject: Re: Should software documenters learn to read code?
From: Janet Swisher <jmswisher -at- gmail -dot- com>
To: "<techwr-l -at- lists -dot- techwr-l -dot- com>" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 13 Feb 2009 10:40:54 -0600

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.

Visit my blog at:

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:

Should software documenters learn to read code?: From: Downing, David
Re: Should software documenters learn to read code?: From: Deb McNally

Previous by Author: Re: Meetings -- ARRGGHHH!!!
Next by Author: Re: Qualifications for an off shore writer?
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