If you have ever worked as a technical writer, you probably have an image of what writing documentation for free software would be like. You might imagine the writer as a lone figure in a corporate department, using proprietary software, and chasing down developers to plead for information, much like most technical writers anywhere. But while you might find a few positions like that, the chances are that every one of these pre-conceptions would be wrong in practice.
Tools of the Trade
True, you might find yourself working in a typical corporate structure, although a non-profit is just as likely. Yet, even if you do, you may find that your connections extend far beyond the company that pays your salary. Although you may be working from a home office, your interactions might be wider than ever. You may find yourself cooperating with volunteers, perhaps even with employees of rival companies in a software project, or involved in a documentation project like FLOSS Manuals (https://flossmanuals.net/). You may also be hearing directly from the users of your manuals and help files about how usable they are.
Quite simply, the boundaries of your work are likely to be more flexible than in the typical IT environment. Not that this is a bad thing — if nothing else, if you are just beginning a career in technical writing, it means that you can gain valuable experience and some samples for your portfolio by volunteering for a project. But the atmosphere is likely to be different from what you were told to expect in the class room or by your peers in other tech-writing gigs.
For another thing, your software experience will probably only be useful so far as you can extract general expectations about what features to expect. As Jean Hollis Weber, a member of ODF Authors, a project that documents Apache OpenOffice and LibreOffice (http://www.odfauthors.org/openoffice.org/) explains:
“Tools used in open source projects are typically different from those used in commercial situations. Tools are genrally open source: big name tech-writing packages (FrameMaker, Microsoft Office, AuthorIt, Visio, Photoshop, and others) are replaced by LibreOffice, Scribus, GIMP, Inkscape, Docbook, and others, or documentation is entirely online, typically wiki-based. You may be required to do screen captures from a Linux platform.”
You may also need to learn the basics of version control, so that your work in progress can join that of the rest of a project’s.
Who Owns Your Work?
These expectations are the norm because, as the Free Software Foundation expresses it, those involved believe strongly that “Documentation for free software should be free documentation, so that people can redistribute it and improve it along with the software it describes (https://www.gnu.org/licenses/).”
Which brings up another point that needs emphasising: in most tech-writing positions, your work is owned by the company. By contrast, your work for free software is “free” — that is, licensed to encourage other people to use and change it. As a writer, you will save yourself endless confusion and wasted outrage over imaginary mis-uses if you learn as soon as possible whether your work will be released under the GNU Free Documentation License (https://www.gnu.org/copyleft/fdl.html), Creative Commons Attribution – Sharealike (https://creativecommons.org/licenses/by-sa/3.0/us/), or some other free license.
For that matter, your work will be easier if you understand — or, better yet, sympathize with — free (https://en.wikipedia.org/wiki/Free_software) and open source (https://en.wikipedia.org/wiki/Open-source_software software). Even those who are paid for their efforts routinely have some degree of idealism about them, as well as a conviction that they are doing something that many people could use.
If you treat your work as just a way to earn a pay cheque, then not only will you have little sense of why the software you are documenting exists, but you are also likely to have frequent clashes of temperament. You will almost certainly be unhappy about your involvement with free software.
Where a Writer Fits
However, these adjustments of expectations are only the beginning. The attitudes of mainstream IT often leak into free software, but in many cases you will find them vying with a very different set of assumptions about how a writer should work and interact with those around them.
One of the first assumptions that you should discard is that a writer’s role is simply to write, or at best record what so-called subject matter experts tell them. Most projects are too small for anyone to specialize, which means that you will be expected to be your own expert.
Just as importantly, many in free software believe they are in a meritocracy, where people are judged by their competence. Although the belief is questionable, it is so widely held that a writer who is unable to learn quickly and relies on others instead risks being regarded as a dead weight rather than an asset.
As Tony Chung, a member of the Techwr-l list (http://www.techwr-l.com/) told me, “Open source developers tend to respect others like themselves. They frown heavily on noobs who don’t dig first [and] ask questions later.” Or, as Anne Gentle, a writer from Rackspace, advises in a blog entry, “Become as technical as possible.” (http://justwriteclick.com/2012/09/13/career-focus-community-documentation/) Nobody in a project will expect you to be an expert from the start, but they will expect you to get up to speed quickly and as much as possible by your own tinkering.
In addition, like everyone else, writers will be expected to get involved in the rest of the project. Because writers may be the first outside the programming team to see an application, they are frequently encouraged to file bug reports.
For the same reason, Techwr-l member Robert Fekete points out, writers are often called upon to become usability testers:
“when thinking about features, developers think code-wise — that is, how to implement it, which code libraries and classes to use, and so on, and tend to neglect the aspect, ‘how will the user use it?’ How will they want to use it [and] in what scenarios? Is it easy to start using the feature, or do you need to configure things at five different places that do not even seem to related? Are the names of the options meaningful to the user, or just obscure abbreviated function names?”
Of course, writers can fill the same role in any job, but usability is still a relatively new concern in free software, so the role can be even more important than in the average tech-writing job.
Other roles that writers often fill in a free software project including marketing, maintaining the web site, helping users on a mailing list, and moderating or participating on the developers’ mailing list — and, most of all, participating in peer review and submitting their own work for general criticism. Little could be further from the usual image of a writer working in isolation or a small group of fellow writers and adding the results at the last minute before a product ships.
Demands and returns
Undoubtedly, free software demands more of technical writers than most proprietary companies. Part of the reason is that documentation has only become a major concern in free software in the last six or seven years, so that the role of writers is still being defined. Another is that experienced writers are rare in many projects, and there are always more things to do than people to do them.
However, the trade off is that competent tech-writers often have the opportunity to define their jobs in free software. The scenarios in textbooks that never seem to be implemented in practice, such as being a user advocate, or documenting from the start of development, can sometimes exist in free software.
In fact, Adam Hyde, the main contact for FLOSS Manuals, suggests that there is still opportunity for technical writers to take a leading role in free software:
“Free software projects have a lot to learn from the people who document software. Documentation is at one of the frontiers of collaborative production. Free documentation embodies the principles of free as in libre in its choice of toolset, licensing, and collaboration. Free documentation is more open than programming, because there is less technocratic gate keeping going on. Free documentation is one of the most open writing practices around, and often more free than free software.”
Such potential may not be for everyone. But technical writers who prefer their work with a dash of idealism and opportunity should consider specializing in free software Writing free software documentation, they can learn in a month what would take them a year in other tech-writing gigs — providing they can check their assumptions at the door.
Bruce Byfield was a technical writing consultant for nine years. During that time, he worked for over 60 different clients, ranging from single person startups to IBM and Intel.
Image credits:
Fountain pen — public domain, courtesy Wikimedia Commons
