Hitching with Clipboard and Pen Along the Open Road: A Tech Writer’s Guide to the Open Source Movement (Part Two)

In Part One of this two-part series, you got a look at the history of the Open Source movement, saw how Open Source projects can be a positive environment for technical writers, and got an introduction to the Free Documentation License.

Following in Part Two, you’ll find out about tools that Open Source writers use, opportunities available for tech writers in the Open Source community, and resources for finding Open Source documentation projects. This two-part series is not meant to cover all aspects or issues about the Open Source or Free Software movements. Instead, it is meant to provide a starting point for asking questions and learning more about how these movements apply to the technical writing community.

The Writer’s Toolkit

Until recently, most Open Source projects were small. They focused on the needs of the developers who wrote them. Aside from the GIMP, a graphics program that rivals PhotoShop for complexity, productivity software was rare. Several Open Source office suites are being developed, but, for now, writers may have to choose between efficient tools and remaining true to the Open Source ethos.

If you work on Linux, the largest center of Open Source projects, you can find several writing tools; however, balancing features and ideals is a constant challenge. For example, Applixware Office boasts a full set of features, but it is not available for download and is closed source. Corel Office, by contrast, is closed source but is available for free download. The Linux Framemaker beta is also free for the download; however, Adobe may never issue a finished product. On the other hand, LaTeX, a professional typesetting program, is free software, but, like QuarkExpress, is a poor choice for documents that will be frequently revised.

Online help is even more difficult. No help authoring tools comparable to ForeHelp or RoboHelp exist, unless you are documenting Java applications, in which case you can use JavaHelp. Further, choices for help formats are limited. WinHelp doesn’t exist on Linux or BSD (obviously), so the options are either plain text or HTML. If you choose HTML, editors like Bluefish are available. Just don’t expect WYSIWYG–most of the free HTML editors display only the raw code.

The most complete documentation tool available is DocBook, a Document Type Definition for SGML and XML. Although one poster to TECHWR-L called DocBook “the DTD from Hell,” DocBook’s difficulty is mostly a result of it being so fully featured. At any rate, a promising WYSIWYG editor called conglomerate may soon make DocBook easier to use. Other free software, such as jade or doctools, allows you to export DocBook files to formats such as HTML, PostScript, or RTF.

The importance of DocBook is indicated by the fact that, on July 16th at the Open Source Convention in Monterey, the members of the Open Source Writers’ Summit voted to standardize their free software documentation on DocBook. Still, DocBook does not provide any tools for document maintenance. Also, because Summit members appointed themselves to make the decision to standardize, the decision may not influence other writers.

At the same convention, on July 19th, Sun Microsystems announced that StarOffice would become an Open Source office suite in October 2000 under the name of OpenOffice. For writers used to traditional tools, this may be the most promising development yet. StarOffice, which has been available for almost a year as a free download, is in many ways a Microsoft Word clone. Unfortunately, just enough differences exist to make switching from Word to StarOffice confusing. Many writers using StarOffice also report difficulty with managing long documents, which is a problem also reported in using Word.

Those interested in a traditional tool will have to wait to see whether OpenOffice improves the product and see how quickly the improvements come. The T-shirt that came with the announcement was popular enough at the Open Source convention–a white shirt with “Freedom” written dramatically over the left breast and with the Web site for the project on the back–but geeks will wear anything, so long as it’s free. And, in fact, mutterings about “bloatware” were as common after the announcement as the shirts.

For now, the only bright spot in free documentation is that versioning control software such as CVS is freely available. In fact, the latest version of the Mandrake Linux distribution installs both CVS and DocBook for you. Otherwise, the most you can do is wait, improvise, and try not to sink your teeth into the nearest Open Source throat in frustration.

Down the Road

Serious documentation for the Open Source movement is barely on the entrance ramp. For writers who want to make their marks or to set standards for an entire industry, it offers a high octane opportunity. With few exceptions, the standards of writing are so low that any trained technical writer who can adjust to the culture should have no trouble hitching a ride on the Open Source movement.

What’s more, the opportunities are only getting better. Despite the lack of tools, documentation is becoming a major concern in the Open Source and Free Software movements. The recent release of the Free Documentation License, to say nothing of the upcoming releases of free office suites, such as Koffice (which includes Kword, a FrameMaker-inspired word processor), are proof of a growing respect for documentation.

Whether writers will respond to this opportunity is uncertain. In 2000, writers are in the same spot that coders were in 1984, when the Free Software Foundation was established. We’re watching a new phenomenon, but we’re not sure what to make of it.

Meanwhile, those of us who hitch a ride on the Open Road may sometimes feel challenged. Our moods may swing from delight to frustration as quickly as the flatbed of an empty pickup truck. But, whatever we feel, we can be sure of one thing: we’re never going to be bored.

How to Find Open Source Writing Projects

If the Open Source movement continues to grow at the same rate, you won’t need to find writing projects. They’ll find you. Meanwhile, you can find projects at a number of sites, including these:

  • SourceForge (http://sourceforge.net): a site that matches high-tech workers with companies funding Open Source projects.
  • SourcXchange (http://www.sourcexchange.com): another site that matches high-tech workers with companies funding Open Source projects.
  • The GNU Foundation (http://www.gnu.org): the home of the Free Software Foundation. It’s also the place to learn more about the GNU Public License and the Free Software movement. Most of the free software projects listed on this site are volunteer efforts.
  • The Open Source Writer’s Group (http://www.ibiblio.org/oswg): a site for Open Source writers. It includes discussion groups, as well as pages where you can list yourself as a writer, editor, or translator, or search for an interesting project.
  • The Linux Documentation Project (http://www.linuxdoc.org): a site for volunteer efforts for documenting Linux in general.


Category: Open Source Tools - Tag (s): DocBook / GNU / HTML / Linux / SourceFourge / XML

Hitching with Clipboard and Pen Along the Open Road: A Tech Writer’s Guide to the Open Source Movement (Part One) | Online Magazine for Technical Writers TechWhirl Magazine

13 years ago

[…] for Part II?  Right this way Tweet reddit_url = […]

Subscribe to TechWhirl via Email