Re: THANKS! Re: Software engineer tech. writers? Do they exist?

Subject: Re: THANKS! Re: Software engineer tech. writers? Do they exist?
From: Laura Lemay <lemay -at- lauralemay -dot- com>
To: Dossy Shiobara <dossy -at- panoptic -dot- com>
Date: Tue, 04 Sep 2007 10:40:30 -0700

Dossy Shiobara wrote:
> I'd like to follow-up with a second question: while it's not unusual for
> a software developer to contribute code to an open-source software
> project, I haven't (personally) seen much evidence of tech. writers
> contributing documentation, manuals, etc. to open-source software
> projects.
> Why do you suppose this is?

I had thought I had seen some research on this at some point, here, on
the STC, on the O'Reilly web site, but I can't find it, so perhaps I
just imagined it.

The short answer, to generalize and stereotype from my experience, is
that tech writers simply don't get the same benefits that developers do
from contributing to open source, even if they do regularly use and
believe in it.

People have studied motivations for developer contributions to open
source projects and the usual reasons have come up: "scratching an
itch," being part of a community, building one's reputation capital
("whuffie"), or getting actual economic benefits from contributing (more
companies are seeing open source contributions as a significant resume
plus). In addition most OSS developers I know simply love to program:
they do it all day for their day job and then go home and do OSS.
Programming is a passion.

For most technical writers, however, technical writing is a job, not a
passion. We write at work but we're not, for the most part, going home
and writing manuals in our spare time. (Please don't all of you reply to
me and say 'it IS a passion for *ME*'; I am generalizing) When we
write at home its more likely to be personal writing projects unrelated
to technology -- fiction, journalism, blogs.

There *are* economic and reputation benefits for us to doing tech
writing on our own time -- but not necessarily for open source projects.
There is a decent market for our technical writing in computer books
and magazine articles. If we have the time and the energy and the
interest to do technical writing outside of work chances are OSS
projects will lose out to those that actually pay us for our work.

For beginning writers, working on OSS projects is an EXCELLENT way to
build a portfolio, and one that is recommended regularly on this list.
I know many larger OSS projects with budgets that have hired writers
full time based on the volunteer work they have done for that project.
So working on OSS projects does have a career benefit, to some extent.
But I know very few commercial companies that are the least bit
interested in whether a writer works on open source or not. IME only a
company that was itself involved in OSS would be interested to see an
OSS writer. Its mostly irrelevant to the career prospects of a tech
writer otherwise.

As for the community aspects -- this is probably the most compelling
reason for a writer to contribute to an OSS project. Giving back to the
project, and being part of a team that is making something good can be
very enriching when its done well.

But there's that "when it's done well" part. Again, here comes a huge
generalization: a common issue with OSS projects is the feeling that
there is an implicit caste system amonst contributors: Developers, and
everyone else. I have heard this complaint from writers, designers, QA
folk, project and release managers -- that non-coder OSS contributers
are not as valued as coders on OSS projects, and that only the coders
matter as far as the design and direction of the project. The "others"
feel or that their input is not respected or outright ignored because
they aren't coders and thus not "real" contributors. Depending on how
hostile the environment actually is -- again, generalizing, it varies
wildly from project to project, and I am not accusing anyone of anything
-- this can EASILY negate the good feelings a technical writer has about
contributing to a project, which leaves no reason at all for a writer to
contribute, even if they want to.

Finally there is the issue of OSS projects that are user-related versus
those that are developer-related. Most technical writers are not
themselves developers. So the few technical writers who are willing to
work on OSS projects are more likely to work on user-related projects
because it is something they are more likely to have used themselves or
to be comfortable running and exploring themselves. Developer-related
OSS projects are going to have an extra special hard time getting
writers involved.

I don't have answers for these problems, other than throwing money at
the problem. I suspect a better approach for getting writers for an OSS
project is to view the issue as simply getting writing DONE for the OSS
project. Recruit developers or active posters from your forums to do
writing, use wikis and forums rather than traditional documentation,
make sure API docs are as automatically generated as possible, or run
documentation contests (win prizes for the maximum number of updates!).
For the more touchy-feely community issues make sure that everyone is
credited (no anonymous documentation, ever) and be sure that your
non-coder contributors input is valued.

I apologize for writing such an essay. Hope this helps.


(is AOLserver the former NaviServer? I think I worked on that....)

Laura Lemay Killer of Trees lemay % lemay %


Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

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.


Software engineer tech. writers? Do they exist?: From: Dossy Shiobara
THANKS! Re: Software engineer tech. writers? Do they exist?: From: Dossy Shiobara

Previous by Author: .chm file not opening in Windows XP
Next by Author: RE: OT-Need Wireless Laptop?
Previous by Thread: Re: THANKS! Re: Software engineer tech. writers? Do they exist?
Next by Thread: Re: THANKS! Re: Software engineer tech. writers? Do they exist?

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

Sponsored Ads