Issue #21: Open Source,  Library

The Community

It would of course be easy to single out authors who have made important contributions to the world of Free, Libre and Open Source Software for this month’s Library article. I’m sure we’ll address their work in later issues. One of the most important reasons for the success of Free Software is its collaborative nature so this month we’ll acknowledge the community effort to document open source software.

We start by enumerating the successful commercial efforts that were kickstarted by the work of the community. When Tim O’Reilly diversified his publishing house, O’Reilly and Associates, from technical writing services to publishing, a significant part of their catalogue came from printed copies of manuals for UNIX and GNU tools. Even their bespoke titles, like Programming with GNU Software, advise people to inspect the man and info documentation for the tools.

GNU Texinfo, by the way, is a much-overlooked source of fantastic information. As users of Unix-like systems of any level of experience will realise, the manual pages in man tend to be brief synopses of the behaviour of each option to the tools they cover, but aren’t presented in a way that helps unfamiliar users adopt the tools. Texinfo documents can be turned into websites, books, or online manuals, are hyperlinked, and usually contain much richer information than the man page for a command. The man page for a C compiler might be eight (printed) pages of command-line options, while the info manual for gcc runs to over a thousand printed pages.

Anyway, as O’Reilly filled a gap for high-quality printed documentation for Unix systems (printing those 1,000 GNU pages on an Epson FX-80 takes time, drives you mad with the noise, and you end up with low-quality output), others were providing the community-written documentation as the documentation for their systems. Flip to the back of your NeXTSTEP developer manuals—a cubic foot of paper almost exactly the dimensions of the workstation—and you’ll see documentation for gcc, gdb, and make. This documentation wasn’t written by the team at NeXT: it’s the GNU project’s work. Similarly SUN’s manuals for Solaris—a significantly larger and heavier set of binders that took up an entire shelf in my first office—were hardcopies of the manuals from AT&T, Berkeley, and other contributors.

When Linux became popular among hobbyists in the 1990s, the need to go beyond reference documentation to how-to guides and goal-oriented tutorials became obvious. Once again, the community stepped up. The Linux Documentation Project offered guidance on everything from switching from Windows to brewing coffee with Linux. With TLDP, the documentation went a long way toward meeting the user: no longer a reference of what the functions in the software did, these HOWTO guides told the community how to achieve their goals using free software.

There has always been a need for quality documentation alongside free software projects, even when the most vehement of zealots don’t recognise it. Whenever an ignorant programmer derides someone’s question by demanding that they “RTFM”, they are of course relying on the existence of The Fucking Manual and the (often voluntary, community) labour that has gone into producing, translating, and sharing it. Whenever someone gives up on the official guides and asks StackOverflow how to solve their problem, they’re contributing to a community-supported project to make some startup dudes rich placing advertising in a collaborative documentation project. Indeed the current leader in the Stack Overflow popularity contest got his internet points by documenting the open source .NET and Java developer tools.

In our way, we’re contributing to the free information available on software, too. Please chip in to support our work!

Photo by Museums Victoria on Unsplash.

Graham is a senior Research Software Engineer at Oxford University. He got hooked on making quality software in front of a NeXT TurboStation Color, and still has a lot to learn.