[FM Discuss] Tech writers and FLOSS (was Re: DocTrain Report)

[Janet Swisher]

On Sun, Nov 2, 2008 at 9:16 PM, adam hyde <adam at flossmanuals.net> wrote:
> Hey Janet,
>
> Wow...cool comments :) Many thanks for fleshing out and giving depth to
> my newbie overview.
>
> I was wondering if you think we can tempt many Tech Writers to FM to
> contribute? I found many people interested but then I also found in the
> sessions there were many that were hesitant to do anything wiki-like or
> go near free software...its a diverse profession as you point out but I
> hope we might be able to find the right arguments to convince more TWs
> to participate...

David Cramer and I have been discussing this for a few years, now
(though not about FLOSS Manuals, specifically, of course). We even put
together a presentation about it for the STC annual and regional
conferences in 2006. Our main argument was that working on open source
documentation is a great way for tech writers to expand their skills
and portfolios. I don't know that we actually convinced anybody, but
we may have expanded their horizons a bit.

There is a significant fraction of professional tech writers who only
do tech writing in order to support their fiction-writing habit. So
any off-hours writing that they do is going to be spent on the Great
(Insert Nationality Here) Novel. (BTW, November is National Novel
Writing Month: http://www.nanowrimo.org/eng/whatisnano -- if you don't
hear from your favorite aspiring writer for a while, this may be why.)

However, one things that professional tech writers need in order to
get hired is a portfolio of writing samples. Getting writing samples
can be a chicken-and-egg problem: you need samples to get a job, but
if you don't have a tech writing job, where do you a chance to create
samples? Documenting open source software seems like a logical choice
(to you and me). The unfortunately more common advice is to document a
procedure you are familiar with, or a product that has bad
documentation and make it better.

In the absence of FLOSS Manuals, getting involved in open source
documentation can be quite an intimidating prospect -- picking a
project, figuring out how to get involved, getting accepted by
developers, understanding the code for the project, learning the
documentation tools -- that's a lot of hurdles. FLOSS Manuals pretty
much eliminates the tools issue, and Book Sprints can remove a lot of
the other ones.

The folks that are most in need of writing samples are people entering
the field, either straight out of college, or as career changers.
These groups overlap, because career changers often get some schooling
in technical communication, anywhere from a few classes at their
community college to Bachelor's or Master's degrees. (At least they do
in the US; such programs are much less common elsewhere.)

Another idea that I've tossed around but not done anything about is to
have the documentation equivalent of Google's Summer of Code
(http://code.google.com/soc/2008/). The interaction design community
has something called Season of Usability
(http://season.openusability.org/index.php/home). The idea would be to
get students in college technical communication programs to work on
FLOSS documentation projects, with oversight by professional tech
writer mentors. It might be easier to get the pros involved as
mentors, since it requires less work and seems more warm and fuzzy.
OTOH, there just isn't as much awareness of FLOSS among tech writers
as there is among programmers, so there would still be some
consciousness-raising needed.

In order for someone to be able to use an open source document as a
writing sample, it needs to be mostly their work. Some collaboration
and editing by others is OK (it works that way in industry, too), but
the person needs to be able to credibly tell a prospective employer
"*I* wrote this".

The other thing that can attract tech writers to open source projects
is the opportunity to learn technology that they otherwise wouldn't
get a chance to learn, either in terms of the content of the project,
or of the tools involved. Unfortunately, the sets of tools used in
open source documentation and those used in industry have been almost
completely disjoint, aside from HTML and CSS. The DocBook tool chain
has had some crossover, but most tech writers haven't heard of it. The
DITA Open Toolkit is the first to really bridge the gap.

Are you going to be using DITA to do the DITA book sprint? Seems like
eating the dogfood would be expected in that case. And if you do, I
expect that there would be a lot of folks eager to get some real-world
experience using DITA, given its high buzzword value. What could be
cooler than saying in an interview "DITA experience? I helped write
the book on DITA!"

So those are my thoughts on your question :-)

--Janet