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

Subject: RE: THANKS! Re: Software engineer tech. writers? Do they exist?
From: "Gordon McLean" <Gordon -dot- McLean -at- GrahamTechnology -dot- com>
Date: Wed, 5 Sep 2007 08:00:22 +0100

To build on what David says, and having contributed to two similar projects
(both now dead), there is an additional 'barrier'.

In my own personal experience, a lot of the developers who get involved with
OSS are very passionate about their code, but can't raise their heads high
enough to see the "product". Asking questions about who the target audience
is, why they would use function X, or why function Y isn't on the same
screen as widget Z... All those questions tend to disappear into the ether
and remain unanswered.

It seems that the OSS projects which survive and flourish are those with
enough "product" people in the mix and, 9 times out of 10, they already have
good documentation. Those that are very popular but don't have any
documentation, or have a limited/poor set of docs, tend to be very
specifically targetted and can 'get away with' not having a great set of

Note: I have tried to get involved with a handful of OSS projects over the
past 10 years. It may be I chose badly or it may be that I am the common
thread! As ever YMMV and other acronyms...


-----Original Message-----
From: techwr-l-bounces+gordon -dot- mclean=grahamtechnology -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+gordon -dot- mclean=grahamtechnology -dot- com -at- lists -dot- techwr-l -dot- c
om] On Behalf Of David Castro
Sent: 04 September 2007 23:05
To: Dossy Shiobara
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: THANKS! Re: Software engineer tech. writers? Do they exist?

On 9/4/07, Dossy Shiobara <dossy -at- panoptic -dot- com> wrote:

> 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've considered joining a project as a tech writer, but a few things have
stopped me.

First, it can be daunting to figure out exactly *how* to get started.
Recently, I looked into joining an OSS Eclipse plug-in project (it provides
an interface for MySQL and other databases). The project specifically
requested new contributors (I think it might have even asked specifically
for writers), and had a forum for new people to post to. I posted with a
brief bio, explaining that I have 12 years of writing experience, and 8+
years of hobbyist-level Java experience.
While other people who posted got a response, mine never did. So, I simply
forgot about it.

Another time, I wanted to contribute to a project, but I couldn't tell if
they *needed* a writer. Their docs were actually pretty doggone good. And,
again, there was no central contact for new contributors, so I had no way
(that I could figure out) to find out if they needed any more writers.

Then there's the issue of needing to learn new tools in order to start
contributing. If you don't know how to use CVS, you're pretty much dead in
the water for most OSS projects. I know enough about CVS to basically be
dangerous. I use Subversion at work, which is a derivative of CVS, and have
managed to not cause damage, but I can't say I'd be as comfortable with
uploading content to a shared repository for an OSS project. (I do realize
that I would not be able to commit changes at the outset, so this is
probably not that big a
deal.) Some projects require other tool knowledge, such as XML for
documentation. If I have to learn a new tool to start contributing, I'm
probably not going to be as interested.

And finally, there's the issue with finding a project that both appeals to
you, and needs you. Part of the joy of doing OSS is knowing that the people
who use the tool appreciate you, and want you to be doing what you're doing.
We, as writers, need a place to find out about the different projects out
there that actively *want* writers, editors, indexers, technical artists,
help designers, and so on. I could have sworn someone on the list several
years ago suggested creating such a repository, but I don't believe I've
heard anything about it in the meantime. (If there *is* such a resource,
please do tell me about it!)

-David Castro
thejavaguy -at- gmail -dot- com

This email (and any attachments) is private and confidential, and is intended solely for the
addressee. If you have received this communication in error please remove it and inform us via
telephone or email. Although we take all possible steps to ensure mail and attachments
are free from malicious content, malware and viruses, we cannot accept any responsibility
whatsoever for any changes to content outwith our administrative bounds. The views represented
within this mail are solely the view of the author and do not reflect the views of the organisation
as a whole.
Graham Technology plc
Registered in Scotland company no. SC143434
Registered Office India of Inchinnan, Renfrewshire, Scotland PA4 9LH


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.

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

Previous by Author: Avoiding documentation bottlenecks while maintaining quality? (take II)
Next by Author: RE: versioning software
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