Author: Scott Nesbitt
Documentation is one area in which free/libre/open source software (FLOSS) is weakest. A project called FLOSS Manuals is trying to remedy this situation. The idea behind project is to create quality, free documentation for free software.
FLOSS Manuals is the brainchild of digital artist Adam Hyde. Hyde doesn’t have what some would consider to be the typical background of a FOSS contributor. In his various lives, Hyde ran independent radio stations in New Zealand and managed Internet service providers in Australia and the Netherlands.
However, the genesis of FLOSS Manuals follows the classic pattern of an open source project: scratching a particular itch. To earn a living, Hyde ran workshops on free and open source software, and started developing documentation for the workshop participants. He realized that “the state of documentation for free software was pretty appalling. So, I went from documenting my workshops to putting those documents on the Internet to adding more and more to it.” From there, he put the documentation on a wiki to better manage it.
Hyde then decided to make the content more accessible so that more people could read it, extend it, and use it in the way in which they wanted. He created FLOSS Manuals as a nonprofit organization in 2007.
At the moment, the FLOSS Manuals Web site hosts more than 30 guides of varying sizes and completeness on software such as Inkscape, VLC, Blender, and Audacity.
Hyde hosts the documents “free, as in gratis and libre.” They’re licensed under the GNU General Public License (GPL) version 2. Where necessary, the GNU Free Documentation License (FDL) is used in conjunction with the GPL.
In addition to the content that’s available at the FLOSS Manuals Web site, you can download print-quality PDFs of some of the manuals from the project’s bookstore at Lulu.com (a print-on-demand service). Professionally printed and bound copies of those books are also available for sale at Lulu.com.
FLOSS Manuals encourages people to share the available content. On the printed books are the words “Please Copy!”
The tools
Instead of using a content management system, the FLOSS Manuals development team hacked a popular wiki engine called TWiki and created its own set of plugins to make it less like a wiki and more of a collaborative authoring system.
The editing interface is similar to that of a word processor, and insulates authors from wiki markup. There’s also a one-button publishing process, which lets an author generate static HTML and a PDF from the content. Hyde says he’s learned a valuable lesson from interacting with professional technical writers: don’t overburden the tools with features.
On top of that, FLOSS Manuals has added some tools that make collaboration easier. Recently, the site implemented a chat tool that lets authors communicate in real time while editing a document. The goal of the collaboration tools is to “jell the community that’s online at any given time.”
You can read the books at the FLOSS Manuals site, or generate a PDF file of any of the books using HTMLDOC. All the publishing work is done on the server side.
But you don’t have to take each document as it’s presented. The content is a set of discrete chapters, and a remix feature lets you pick the chapters you want, via drag and drop, and create a personalized book from it. You can download it as a PDF or as a set of HTML files in a compressed archive with a choice of covers and with custom CSS for formatting. There’s also a feature that generates HTML code you can use to embed the remixed manual on a Web site or in a blog.
Sprinting to the finished product
FLOSS Manuals has taken advantage of “book sprint” events to create books within a short period. Hyde got the idea from Thomas Craig, who put together a group of people to write the book Wireless Networking in the Developing World. When the two men discussed the process, Hyde “saw how it could be very useful to form content communities around specific topics and specific software.”
Each book sprint involves gathering a group of people in one location to write, edit, and publish a manual in five days. It’s not just a matter of dropping people somewhere and getting them to write from scratch. There’s a lot of up-front work done before everyone convenes. Hyde gathers information on the subject of the book, creates a structure for the document, finds a venue, rounds up participants, and even shops to meet the various dietary needs of the participants.
“We have the tools and the methodology to go from almost nothing to a book in five days,” Hyde says. At the most recent Book Sprint, to write a book on bypassing Internet censorship, Hyde says “we started at 9:00 a.m. on a Monday and at 6:00 p.m. on Friday night we cracked open some beers and pushed the Publish button. We had a 200-page print-ready PDF, uploaded it to a print-on-demand service, and you could buy it by five past six.”
That event and another book sprint documenting how to use the XO Laptop and its Sugar interface successfully produced several hundred pages of documentation this year.
Form and function
Hyde insists on the importance of aesthetics in manuals. “Documentation has to have an aesthetic strategy,” he says. “Documentation has to be consumable. It has to be friendly, not just in the way it’s written but in the way it presents itself. It should be easy to read. It should look attractive. It should look like something you want to engage with.”
Of the manuals that are available at Lulu.com, Hyde says, “If you look at them, the books are very smooth. The chapters dovetail into each other. There’s a real consistency of terminology, and there’s a real flow to the books.
“Documentation as a whole has always looked a little too nerdy. We’re trying to make it friendlier.”
Getting social and building a community
As much as putting out quality documentation, Hyde is interested in building a community around FLOSS Manuals. A major reason is sustainability. “If we have a community that we can draw from to maintain the documentation, its lifespan is vastly improved.
“Writing has been stuck in this terrible, romantic format of the lone writer,” Hyde says. “Writing is a social process. How many times have you heard people say ‘I was commissioned to write a book,’ or ‘I wanted to write a book but never did’? But if you shut people in a room for a week with seven other people with the same interests, they have a ball and they write a book.”
Of course, getting people together has its hazards — but not necessarily in the way that you’d think. “You get people together who are passionate about a specific topic, provide them with a comfortable working environment, and all they have to do is work then all they’ll do is work. Sometimes you have to tell everyone to get out of the room, get some fresh air and take a break. Sometimes they demand it, but not often. Other times, you just have to let people get on with it because that’s what they’re enjoying.”
Looking to the future
The future is definitely on the minds of the FLOSS Manuals team. Aside from planning book sprints for the coming year, Hyde is hoping that FLOSS Manuals will be able to take on its first paid staff member — a coordinator who can take over some of the tasks that he’s currently shouldering.
The recent fork of Twiki is also a concern. “With the fork, we’re re-evaluating our technical strategy. We’re thinking of rebuilding the whole code base from the ground up.”
Currently, the documentation on the FLOSS Manuals site is aimed at the average computer user. “We haven’t got any manuals yet which are hard core technical manuals,” Hyde says. “Most of them go from beginner to the intermediate stage of technology use.” But he adds that “there’s room for those hardcore technical manuals.” Hyde even sees a FLOSS Manuals being used to author and publish API documentation.
Hyde says a broad range of people contribute to FLOSS Manuals — artists, professional technical writers, developers, people in the One Laptop Per Child community, and folks with a casual interest in technology. He says that FLOSS Manuals is a great way for people who aren’t developers to contribute to free and open source software.
Category:
- Community
