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

Mon Nov 3 20:44:14 PST 2008

I was going to reply on the other thread but all I had to say was "I totally
agree with everything said so far" and we all know that's just silly. :) But
I do admire the Ament book on Single Sourcing (building modular
documentation). Chapters are a collection of topics to me. Ament's book
describes topics as answering a basic question. DITA addresses topics in the
same way but forces strict adherence to "one topic per question answered."

I'm in agreement with all of Janet's previous comments - especially
revealing is the "what companies pay tech writers to do" reveals their
current interests. So the TW is not always at fault for the slowness in
uptake of more open, collaborative, modular publishing and authoring
techniques. I think that most technical writers get their priorities set by
their current employer... the people that Janet list (students and those
"breaking in" to the field) are certainly good candidates to help out with
open source doc. But the open source coders just plain love to code and do
their "job" in their spare time because it's their passion. There are those
of us who have technical writing as a passion. They're few and far between
I'd guess, but they're certainly the most techie of technical writers (as
Janet's blog is so aptly named, in fact.) And some of those techie tech
writers have embraced DITA, but mostly it has been adored by XML fans and
consultants who realize that most tech pubs departments don't have the
technical prowess to modify an ant file to create a build. People spend
seven figures to get DITA adopted at larger companies and even 2-3 years in
are still wishing for freeing up their writers' time to write... but at the
five year mark, they most advanced topic authoring implementations are on
cruise mode, having written awesome consistent doc and are now just
constantly monitoring for user feedback and rolling improvements in all the
time (this description comes from discussion at the latest Central TX DITA
Users Group last month.)

Open DITA documentation does exist - there was a contractor who donated
literally months of her time to the project simply because she wanted to
learn DITA. She created the Open ToolKit User Guide using DITA:
http://dita-ot.sourceforge.net/SourceForgeFiles/doc/user_guide2.html.
Although really for an overview, the Apache Derby project has done a nice
job giving writing guidelines for DITA here:
http://db.apache.org/derby/manuals/guidelines.html. Anyway, just pointing
those out as examples but also wondering what DITA doc we could scope for in
a minisprint? I'm sure that's a new thread entirely. :)

I'm not sure how or whether to refute the assertion that many technical
writers are feeding a fiction writing habit. I hear that over and over yet
have only met two in person (out of at least 200 people on my LinkedIn
contacts) who even think they stand a chance of being a fiction writer - but
yes, they both are participating in nanowrimo. :) I sometimes think that the
field is going through an interesting old guard/new guard change and some
writers have left the field for web design and programming and others leave
the field for usability and still others leave the field for business
analysis or process management or quality assurance or... anyway, the
pattern I see is more a flight from tech writing than a stable dedicated set
of career-life techwriters. I'd love to hear feedback on that theory though.
:) Is TechWriting a mere stopping point for a point in time in a larger
career?

Thanks for the great summary trip post and ensuing discussion - I'm so
pleased that DocTrain was a good experience for you and I think that FLOSS
Manuals offers the tech writing world a great example of community
documentation... now if I could only gather my thoughts for a blog entry on
the critical differences between user-generated content and community
documentation. :)

Anne

On Mon, Nov 3, 2008 at 5:43 PM, Janet Swisher <jmswisher at gmail.com> wrote:

> 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
> _______________________________________________
> Discuss mailing list
> Discuss at lists.flossmanuals.net
> http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net
>

-- 
Anne Gentle
email: annegentle at justwriteclick.com
blog: www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.flossmanuals.net/pipermail/discuss-flossmanuals.net/attachments/20081103/46476944/attachment.htm>