Linux.com

Home Learn Linux Linux Documentation Careers in Linux: Technical Writing

Careers in Linux: Technical Writing

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.

http://upload.wikimedia.org/wikipedia/commons/thumb/f/f8/Quill-Nuvola.svg/200px-Quill-Nuvola.svg.png

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.

File:Parchment.jpg

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

Parchment -- public domain, courtesy Wikimedia Commons

 

Comments

Subscribe to Comments Feed
  • Kevin O'Brien Said:

    Bruce, a good article on a topic I have a great interest in. Your comments about figuring things out for yourself and not asking others struck a nerve with me, however. I have written documentation as part of my job, and I was never expected to be as knowledgeable as the developers. Writing an explanation that a non-developer can understand is, to my mind, a distinct skill set and quite valuable by itself. My one attempt at trying to help with documentation on an open source project (a KDE application, as I recall) ran afoul of exactly the attitude you brought up here. So it looks like the culture of open source is one where to help with documentation you have to be 1) a good writer; 2) a good explainer (not the same thing as writer, in my opinion); and 3) good at figuring out software without any assistance. If you do the Venn diagram on that one the area where all three of those overlap is pretty small. For my part, I have given up trying to help write documentation because to me it looks like most projects don't understand how to do it and don't seem to care. What it looks like to me is that they have some idea that they need to have it, but no one on the project wants to be involved in it.. They just want someone else to come and take the problem away. And as long as that is the prevailing attitude there will be very little decent documentation out there.

  • Moose Said:

    What Kevin Said. Yes, you need to understand what you're writing about in as technical a manner as possible. But you don't get that way through some sort of magical osmosis and 'as possible' is the key phrase here. If a programmer is incapable of explaining in clear language what s/he has written, I would be worried. It's a given in FOSS that programmers aren't going to bother with "trivial" things like documentation or, dieties forbid, comments, and that's horrific. I've worked for software projects where programmers who didn't comment their code were sent back to do so by old school managers. The idea of "You should just read the source" is not only still around after at least 30 yrs but clearly shows the exclusionary attitude that too many coders (whether writing FOSS) still have. A very brilliant technical writer friend of mine used to give a talk called, "Why the Documentation Sucks and What You Can Do About It" to systems administrators. The point of his talk was that documentation has to be a two-way street. If a group wants better documentation, they have to help make sure it actually happens. This person has been writing technical documentation for umpteen years. He currently works for A Major Linux Company. His first project for them was to document a particular filesystem. He became an expert on the filesystem not because he spent all his timing reading the code or working with it directly, but because he spent all his time going to the programmers and asking, "What does this actually do?" and "What does this part mean, especially in (some situation)?" The programmers, in turn, were more than willing to answer his questions. Somewhere along the way he discovered that he could talk about the filesystem nearly as fluently as any of the coders. That's the way it's supposed to work.

  • Terry Said:

    OMG .. !!! you are so right .. I am not a Technical Writer but I worked alongside of some contractors and I had some of them tell me the Project leads on the writing of the code etc .. wanted no part in the Documentation process .. they did not want to take the time to let you know .. would not explain anything to you or even considered it ... it is like they wrote it it is theirs .. so if the did documenttation then there would be not need for them or their work would be compromised or someone could figure out their inadequacies .. etc .. really not wanted from what I have seen so far ... good comment above Kevin Obrien

  • Jefro Said:

    Excellent article, Bruce! I was a technical writer for about 20 years, most of that spent in documenting open source, and I can attest that it is a fine career path.

Upcoming Linux Foundation Courses

  1. LFD331 Developing Linux Device Drivers
    13 Oct » 17 Oct - Virtual
    Details
  2. LFS425 Linux Performance Tuning Crash Course
    16 Oct » 16 Oct - Düsseldorf, Germany
    Details
  3. LFS220 Linux System Administration
    20 Oct » 23 Oct - Virtual
    Details

View All Upcoming Courses

Become an Individual Member
Check out the Friday Funnies

Sign Up For the Linux.com Newsletter


Who we are ?

The Linux Foundation is a non-profit consortium dedicated to the growth of Linux.

More About the foundation...

Frequent Questions

Join / Linux Training / Board