The biggest deficiency in free operating systems is not in the software – it is the lack of good free manuals.

– The Free Software Foundation

Documentation is, sadly often treated as a second thought, something to cobble together when the project is almost done. And I'm not saying this out of bitterness as a disgruntled technical writer (which I'm not).

Often, that's not done out of malice. Especially in FOSS projects. It's not that the people running the projects don't want to provide adequate documentation. It's just that many of these projects don't have the time or the hands to create and maintain useful and high quality documentation.

That's a big gap. And it's a gap that the FLOSS Manuals project is trying to fill.

A little history

The FLOSS Manuals project is the brainchild New Zealand native Adam Hyde. Hyde isn't a software developer or a technical writer. He's a digital artist. But like many people in the FOSS world, he started FLOSS Manuals to scratch a particular itch.

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 1

FLOSS Manuals: Too Good to Be Free

By: Scott Nesbitt

Over the years, Hyde ran independent radio stations in New Zealand and managed ISPs in Australia and the Netherlands. Because he had little or no budget, Hyde turned to free and Open Source software to help him in his work. Later on, to earn a living, Hyde ran workshops on free and open source software – specifically software related to streaming media. That's when he started developing documentation for the workshop participants.

Logically, he turned to the official documentation for the software he was teaching as a starting point. He found, though, that:

[T]he 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.

Hyde put the documentation that he wrote on a wiki to better manage it. From there, Hyde decided that it would be more beneficial to have the wider FOSS community be able to add to and improve what he'd started writing, and to add more documentation to fill in the various gaps in the FOSS world. To that end, Hyde registered FLOSS Manuals as a non-profit organization and officially launched it in October, 2007.

Who's involved?

An interesting mix of people. All of them are, of course, FOSS enthusiasts. There are artists and software developers. People with a casual (or more than casual)

interest in technology.

A number of contributors are professional technical writers – at least a couple of whom work for Open Source companies. That said, a majority of the professional technical writers I've spoken to are somewhat contemptuous of FOSS documentation tools and techniques.

A good number of the contributors to FLOSS Manuals are involved in FOSS projects. FLOSS Manuals has worked with the Mozilla Foundation, the Free Software Foundation, the group behind the OLPC and Sugar Labs to write manuals.

The reasons why people get involved are as varied. Some see the advantages to writing free documentation. Others want to give back to the FOSS world.

One person told me an interesting story about how he got involved:

During the Mozilla Summit in Whistler (British Columbia), some good soul watched me sawing at my new Ubuntu notebook. After telling him the whole sad story (...of a Windows user trying for years to climb the Unix mountain...) he gave me THE GNU/LINUX COMMAND LINE manual, hinting that it's no big deal, half a dozen FLOSS dudes have put it together in a day or two. I need somehow to repay the gift.

The project is able to draw on a variety individuals to pull a project together – subject matter experts, users, and professional writers. Unlike corporate documentation teams, or even the teams writing documentation for many FOSS

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 2

projects, FLOSS Manuals collects a broader range of contributors and voices. You get people with varying levels of skill and knowledge who share their experience and insights.

Collaboration and community

And that's the advantage that FLOSS Manuals (and other FOSS documentation project) have: they leverage a community to gain fresh perspectives on a topic. I continually say that the people who use software can have insights into that software which are as valid as those of developers or professional technical writers. On top of that, FLOSS Manuals seems to promote a less formal or stiff style of writing. It's friendlier to the reader.

FOSS is as much about community and collaboration as it is about software. That goes not just for coding, but for documentation as well. With a community, you're able to draw on a lot of expertise and numerous points of view. Theoretically, that should result in a superior product – whether that product is software or documentation.

As much as putting out quality documentation, Hyde is interested in building a community around FLOSS Manuals. A major reason is sustainability. Having a community that FLOSS Manuals can draw from to maintain the documentation increases the lifespan of that documentation.

Why do it that way? As Hyde told me:

Writing has been stuck in this terrible, romantic format of the lone writer. 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. When you get people together who are passionate about something, give them a comfortable environment in which to work, and all they have to do is work then all they'll do is work.

Growth

Starting from Hyde's initial documentation, FLOSS Manuals has grown to encompass 51 manuals (and counting). A majority of the books cover FOSS applications like OpenOffice.org, Firefox, Inkscape, Audacity, and Blender. There is also a comprehensive set of manuals for the XO laptop and a book covering the Linux command line.

The manuals aren't limited to software, though. There are ones that cover topics that are important to members of the FOSS world. Like what? There are manuals covering how to circumvent Internet censorship, how to mentor students involved in the Google Summer of Code, as well as ones that give an overview of FLOSS Manuals and of the project's book sprint process.

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 3

How FLOSS Manuals works

Everything – reading the manuals, writing them, adding to them – is done on the FLOSS Manuals Web site. You wouldn't know it by looking at the site, but it's a wiki. A heavily-customized implementation of the Twiki wiki engine.

The decision to use a wiki was a simple one to make. Hyde looked at a number of Open Source content management systems and none of them packed the features that FLOSS Manuals needed – things like collaborative writing, credit tracking, and indexing. A wiki does, and Twiki also has a number of plugins that allow users to expand the features and functions of their wikis. To fill in any gaps, the developers working on FLOSS Manuals also created a number of plugins. These plugins are available in the Twiki repository.

If you just want to read the manuals, go to http://flossmanuals.net. To write and edit manuals on the site, you need to register for an account. This isn't a security or validation measure, nor is it a way of putting up a wall. It's so that FLOSS Manuals can assign a copyright and a writing credit to you.

Read, write, and remix

There are three activities that you can carry out at the FLOSS Manuals site: reading, writing, and remixing.

Reading is obvious: just choose the manual you want to

read and go from there. You're not presented with a long Web page, though. Even online the manuals are broken down into discrete chapters and sections. You don't have to wade through long blocks of text to find information; you can get to that information with a couple of clicks. If you want to read a book offline, you can create a PDF by clicking the Make a PDF button. On top of that, you can comment on a section by clicking the Discussion link at the top of each page. So even if you're not a registered contributor, you can actually take part in the project. A posting good comment is just as important as writing or editing a section of a manual.

Writing, too, is obvious. That includes not only creating new content, but editing or updating existing manuals. While the FLOSS Manuals site is a wiki, you don't have to worry about learning wiki markup. Everything is WYSIWYG. If you've used a Web-based word processor like Google Docs or Zoho Writer, then the interface will be familiar. All you need to do is start writing and apply formatting from the toolbar.

The most interesting feature of FLOSS Manuals is the ability to remix content. Essentially, you can pick, choose, and publish the information you want in a custom manual. From there, you can generate a PDF file, a set of HTML files, or you can get a widget that you can embed on a Web page or blog.

I've put together a short screencast that shows how the remix feature works.

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 4

FLOSS Manuals has a very nice publishing backend called Objavi. Using Objavi, you can can publish manuals in the following formats:

• PDF

• epub

• ODT

• HTML

When you publish with Objavi, you can choose from 25 pre-set book sizes or specify custom page sizes and margins.

The results look quite good. Which plays into the aesthetic strategy of FLOSS Manuals. I'll be discussing that in a few minutes.

Moving to Booki

A couple of years ago, the Twiki project forked – Twiki's creator took it commercial, and there is at least one Open Source variant called Foswiki. That fork caused Hyde and his team to re-evaluate their technical strategy and to consider rebuilding the FLOSS Manuals code base from the ground up.

The result is Booki. Booki is described as being like a wiki, but instead of getting a Web page you end up with a book.

On the surface, Booki is almost identical to the current FLOSS Manuals site. You can read and write manuals (there's no remix feature yet), and you can publish them in

the same formats as at the FLOSS Manuals site.

You can also import books from Archive.org, WikiBooks, and FLOSS Manuals (as well as epub files) into Booki.

At the moment, Booki is alpha software. There's still a lot of development to do and a few bugs to squash. But it is usable. So much so that people are already using it to write books and the folks behind the FLOSS Manuals project have begun importing books from the FLOSS Manuals Web site into Booki.

If you want to follow the development of Booki, read the project's blog.

Looks can matter

Documentation is often seen as being functional. Whether from the commercial or FOSS worlds, manuals are in many cases kind of plain. But FLOSS Manuals also puts some emphasis on the aesthetics of manuals.

Adam Hyde had this to say:

Documentation has to have an aesthetic strategy. 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.

FLOSS Manuals publishes many of its works using a print-on-demand service called Lulu.com. The proceeds from the

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 5

sales of the printed manuals support the project. The printed books are very smooth – they're well typeset and laid out. The chapters dovetail into each other. There a real consistency in the terminology used, and there's a distinct flow to the books.

FLOSS Manuals also has a portable book binder. That enables them to go to events, generate and print off books, and then bind them on the spot. It's a great promotional idea, and a lot faster and a lot cheaper than going through a print-on-demand service. On top of that, it's quite interesting to watch a book being bound right before your eyes.

The aesthetic strategy applies not only the manuals, but also the FLOSS Manuals Web site itself. Remember that the FLOSS Manuals site is a wiki. The problem with documentation that’s delivered using a wiki is that it looks like it’s being delivered using a wiki. While useful, wikis (at least out of the box) aren’t all that aesthetically pleasing. They’re functional, but they can also be cluttered.

I think you know what I mean: navigation on the top, blocks of menus on the sides, various bits of information in the footers. I don't know about you, but I find that distracting.

FLOSS Manuals tries to remove as much of that clutter as possible. The site has been heavily skinned and the interface made quite minimal. You only get what you need. And that's links to the books, navigation, and the text of the manuals.

All of that's been done quite attractively, too – with a nice choice of colour scheme, icons, and fonts. The site's not too

hard on the eyes, which helps when you're reading!

Sprinting to a manual

FLOSS Manuals regularly holds events called book sprints to pull manuals together within a short period – usually a week or less. Hyde got the idea from Thomas Krag, 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.

You can break the book sprint process down into these steps:

• Come up with an idea for a book

• Find a location

• Get participants

• Get funding

• Front-load on content (if possible)

• Start writing

Each book sprint involves gathering a group of people in one location to write, edit, and publish a manual in anywhere from two to 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 the sprint. Often, the people

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 6

planning the sprint gather information on the subject of the book and create a structure for the document. That structure – it's more of a table of contents or outline – is fluid, even during the sprint.

Then, everyone gets together to write. But you don't have to be there in person to participate; most sprints have several people working remotely. FLOSS Manuals has an built-in IRC client that allows remote participant to communicate with the main group of sprinters.

A sprint is very hands-on; participant use the software while writing about it. For writers who've never used the software before, it's a great chance to learn and share what they're learning. If writers are familiar with the software, chances are they'll learn something new as well as have a chance to share their expertise.

During a sprint there are regular breaks to check on everyone's progress and assign new tasks. Everyone is encouraged to take breaks to clear their heads and get some air. And, of course, to get something to eat. During a number of book sprints, Hyde found that it was often difficult to get people to take those breaks. They were so absorbed in what they were doing that he just let them continue.

At the end of the sprint, you obviously wind up with a book. With longer sprints, the last day is usually quite hectic with people racing to finish content and to edit what's been written. Sooner or later, somebody (usually Adam Hyde) pushes a button to publish the new book on the FLOSS Manuals site. When books are published to Lulu.com (and

not every manual is) you can download a very nicely formatted PDF version of the manual, or order a printed copy.

Even after the manual is published, it goes through an editing cycle. This is to tighten up the writing, eliminate any typos, and to smooth out any inconsistencies in terminology and writing style.

Toronto Open Source Week 2010

As you may or may not know, there was a two-day book sprint held at this year's Toronto Open Source Week 2010 held at Seneca College in Toronto, Canada. This book sprint came about because:

1. For the last two years, I've been promising Adam Hyde that I'd take a more active part in a book sprint

2. I thought that this would be an interesting event to hold at Toronto Open Source Week

The goal was to complete a manual for the Mozilla Thunderbird email client. I co-ordinated the book sprint from Toronto, and Adam Hyde took overall control from Berlin (where he lives).

The sprint was fortunate to have seven students from Seneca College's Technical Communication program involved, along with a graduate of the program who's also former co-worker of mine. A developer who emailed me about the sprint also joined in.

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 7

Blake Winton, a developer from the Mozilla Messaging team in Toronto, was on hand the second day to answer all of our questions. Several people from the Mozilla Messaging Team in Vancouver also took part remotely. Their input and insights were invaluable.

In all, around 20 people were involved either on site or remotely. Not everyone was writing. A number of people were editing and proofreading the book, too. That's pretty impressive.

[A quick aside: I'd like to thank: Chris Tyler, one of the organizers of Toronto Open Source Week and of FSOSS, for generously arranging space and equipment for the sprint; Beth Agnew, who co-ordinates Seneca's Technical Communication program, for helping find student who were interested in taking part in the sprint; everyone who took part in the sprint, both in person and remotely; and everyone from Mozilla for offering support and pitching in.]

The manual was started by a technical writer with Mozilla Messaging named Jennifer Zickerman. We weren't starting from scratch, but there was still a lot to do.

In the weeks leading up to the sprint, I worked with Adam Hyde and some people from Mozilla to nail down what needed to be done. I also co-ordinated with Beth Agnew, the co-ordinator of Seneca College's Technical Communication Program, to find the students I mentioned earlier and brief them on the sprint.

The first day of the sprint started off a bit slowly. There were

three of us on site, and it took us an hour or two to get our footing. On top of that, a bulk of our team, consisting of the students, would be coming in later because they were attending a special seminar that morning.

Once everyone started filtering in, a lot of writing started getting done. It was around that time that the folks in Vancouver were coming online so that really helped.

Adam Hyde was constantly spamming me with helpful advice and hints via email, and we were using the IRC client built into the FLOSS Manuals editing interface to communicate with everyone working remotely.

The goal for day one was to have 80% of the content finished. That's what happened, more or less. Not a bad day's work.

Day two started off pretty much the same way as day one. Three of us got to work at around 8:00 a.m., and the rest of the team started filtering in. Since the previous evening, a couple of new chapters were added and some of the people working remotely added a lot of content.

The goal for day two was to complete the last 20% of the content, then do editing and cleanup. We were supposed to down tools at 1:00 p.m. but I let that slide by half an hour or so. No one tell Adam Hyde, please!

We got to the editing and cleanup, with everyone taking a look at chapters and sections that they didn't work on. Editing and cleanup can be as difficult as writing, but it's also very rewarding. And very necessary. Rewarding in that you

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 8

can really see the final product taking shape. Necessary because you catch all the silly (and not so silly) errors that slip in when you're writing in a hurry. Things like doubled words, missing punctuation, and glaring spelling mistakes.

In the end, the teams wound up writing 14,000 words over the two days. That translated into about 135 pages. Not too shabby.

A few thoughts about the sprint

It was fun. But …

At the end of the first day, my thought was How does Adam Hyde do this without going crazy? Running a sprint isn't easy. Thankfully, I wasn't doing it alone. And I now understand why I avoided the management path during my corporate career.

What's interesting is that I threw everyone into a situation that many professional technical writers would have trouble coping with: getting used to a new tool, writing about unfamiliar software, and rapidly writing in a collaborative environment with a very tight deadline. I have to say that everyone coped admirably.

Remember when I mentioned earlier that in a sprint it's hard to get people to stop working if they're enjoying themselves? A few times I called for a break. No one listened to me; thy all kept typing away.

When you're writing online, it's hard to know how much progress you're making. You don't see a page count or a

word count. Just seemingly endless lines of text and images. So every few hours, I published a PDF version of the manual and let everyone know how many pages we had. That can be a great motivator – for example, that we had 95 pages at noon and 115 pages at 2:00 p.m. shows actual progress.

We ran into a few glitches. There was occasional trouble with the wireless Internet connection; that's to be expected with a network being used by a large number of people. And at one point on the first day, the FLOSS Manuals server stalled. It turns out that the site was being used by a lot of people. We were dead in the water for about 45 minutes, which was a bit frustrating.

I wasn't able to get across to the participants that they needed to write quickly, that they didn't need to worry about making things perfect the first time around. Writers are like that; we try to write everything perfectly the first time. In a situation like this, quantity trumps quality.

I'll let you in on a little secret: the key to good writing is editing. Obviously, I wasn't able to make that clear to everyone.

Overall, I think we did a good job. Could things have been better? Sure. Could they have been worse? Definitely. But in the end, we achieved the goal. All that's left now is some fine tuning.

Everyone who took part in the book sprint can and should be proud of what they did. Every contribution, no matter how small, made a difference.

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 9

Some closing thoughts

In both the FOSS and commercial software worlds, the focus of development is mainly on the software. Documentation is often an afterthought. But good documentation plays a role in the success of a software project. It guides (or, at least, should guide) users from the stages of stumbling in the dark with a unfamiliar application to the point of mastery. At the very least, it should put them on that road to mastery.

Sadly, a lot of documentation in both spheres doesn't do that. Either because it doesn't exist, or it doesn't cover the information that users need. The FLOSS Manuals project occupies an interesting niche in the FOSS world. And it fills a a need – a need for quality free documentation for free software.

The project tries to create documentation that focuses on what users need to know. That stems from the range of voices that contribute to FLOSS Manuals. The books are constantly used, scrutinized, discussed, and updated. As all documentation should be.

Remember that anyone can contribute to FLOSS Manuals. Even if you don't think you can write, you probably have something to contribute – one or more tips or tricks, an update to an existing manual or procedure, an edit or correction. A little goes a long way. By contributing whatever effort you can, you're not only furthering the cause of quality free documentation for free software, but also furthering the adoption of free and Open Source software.

Contact MeWeb site:

http://scottnesbitt.net/

Email:

info@scottnesbitt.net

Blog:

http://weblog.scottnesbitt.net

Twitter feed:

http://twitter.com/ScottWNesbitt

© 2010 Scott Nesbitt FLOSS Manuals: Too Good to Be Free - 10