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

[Laura Lemay]

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.

Laura

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

-- 
*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^
Laura Lemay     Killer of Trees     lemay % lne.com    lemay % gmail.com
http://www.lauralemay.com                     http://blog.lauralemay.com
*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^*^