This is a read-only archive. Find the latest Linux articles, documentation, and answers at the new Linux.com!

Linux.com

Feature: Community

FLOSS Manuals sprints to build quality free documentation

By Scott Nesbitt on December 23, 2008 (2:00:00 PM)

Share    Print    Comments   

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.

Scott Nesbitt is a freelance journalist and technical writer based in Toronto, Canada.

Share    Print    Comments   

Comments

on FLOSS Manuals sprints to build quality free documentation

Note: Comments are owned by the poster. We are not responsible for their content.

FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 158.73.247.16] on December 23, 2008 03:02 PM
"to build quality free documentation"
That's a very misleading title!

#

Re: FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 66.194.130.138] on December 23, 2008 05:20 PM
The comma, is a powerful thing.

#

Re(1): FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 82.192.250.149] on December 24, 2008 10:07 PM
- and you seem to be one of those people who misuse it. There is nothing wrong with the phrase "quality free documentation". The absence of a hyphen distinguishes it from its (almost) opposite, "quality-free documentation".

#

Yep, title is horrendous

Posted by: Anonymous [ip: 199.164.56.5] on December 23, 2008 07:59 PM
"Quality free" is not a descriptor that encourages further investigation. I can only hope the project's documentation is proof read a little better.

#

Re: Yep, title is horrendous: Nope, title is correct

Posted by: Anonymous [ip: 82.192.250.149] on December 24, 2008 10:11 PM
"quality free documentation" is not the same as "quality-free documentation". The title is correctly punctuated. I hope you never get a job as a proofreader.

#

Re: Yep, title is horrendous

Posted by: Anonymous [ip: 164.223.72.5] on December 29, 2008 06:37 PM
If 50% of the readers missed the author's intent with the story's title, what does it matter that the title obeyed some standardization of the English language?

#

Re(1): Yep, title is horrendous

Posted by: Anonymous [ip: 24.38.173.245] on January 08, 2009 03:10 PM
I love quality free documentation because any kind of quality in my documentation just won't cut it lol.

#

FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 161.203.16.1] on December 23, 2008 03:12 PM
Though I agree that free software often has bad documentation, I would argue that this is often true for all software, not just free software. I have used many proprietary software systems that have awful documentation. A great culprit is Microsoft, which now ships minimal documentation with products like Windows; then Microsoft Press will happily sell you a book that should have been the product's manual! On the other hand, many free software products (like Vim, Apache, and most GNU products) have excellent documentation.

#

FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 12.88.34.42] on December 23, 2008 04:08 PM
I have always had better luck with documentation of free software. They are not trying to hide anything. Most opensource and free software I deal with has tons of info on it if you Google or go to the developers home page. Unlike many closed source projects that offer little or no real information, and if they do it is limited to what they want to release to you.

#

Re: FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 67.88.249.34] on December 23, 2008 06:05 PM
I agree I usually fare better in free software for documentation but there are some topics that have giant voids. For example LDAP docs are a little far and wide and it seems nobody in the world knows how to backup Samba tdb's and recover from a disaster.

#

FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 72.39.113.153] on December 23, 2008 06:57 PM
I've found the BSD variants to have generally good documentation, with OpenBSD's being the best, and FreeBSD's coming in at a close second. GNU software seems to me to be less well documented, and Linux kernel related documentation being the worst (the kernel evolves too quickly).

Still, I personally find OSS to have better and more extensive free docs than Windows.

#

FLOSS Manuals sprints to build quality free documentation

Posted by: PerlCoder on December 23, 2008 07:26 PM
I checked out the FLOSS Manuals site. Looks pretty cool! I think this was a really good idea. Some people say that proprietary software is easier to use than FOSS, when the reality is that people are spending millions every year taking classes and buying books to understand how to use Microsoft and Adobe products. (At my University, there is actually a $500 class for learning how to use Excel!)

Having high-quality, easily-accessible documentation available for the more powerful applications could do a lot towards helping the non-geek benefit from Linux.

#

FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 213.198.200.199] on December 23, 2008 09:09 PM
Everyone who claims that FLOSS (in general) has a weak documentation should take a look at FreeBSD (and other BSDs). Every FreeBSD release includes massive documentation improvements and documentation really matches the reality. Take a look at freebsd-doc@freebsd.org mailing list and see how they discuss improvements of FreeBSD Handbook and articles -- all of these being the part of the official FreeBSD CVS repository.

The result of their centralized and professionally planned docs work is uncomparable to anything you can found on myriads of distribution-oriented Linux "wikis" and "user-contributed" papers.

#

FLOSS Manuals sprints to build quality free documentation

Posted by: Anonymous [ip: 72.208.214.148] on December 24, 2008 04:34 AM
Documentation is one area in which free/libre/open source software (FLOSS) is weakest.


I find this statement to be patently untrue. The problem I see is a lack of centralized, organized, official documentation. I'm a consultant and senior-level Linux admin, and I don't remember the last time I googled for how to do X or how Y works and didn't end up with at least a decent explanation or starting point. The documentation and knowledge frequently exists, but lives in source comments, shorthand, or (most frustratingly) forums and mailing list archives.

#

what about wikibooks?

Posted by: Anonymous [ip: 64.81.36.86] on December 24, 2008 07:36 AM
This seems like a case of duplicate effort

#

My name is Tomas Krag, not Thomas Craig :-)

Posted by: Anonymous [ip: 90.184.87.184] on December 30, 2008 01:01 AM
Minor issue, i guess, but seeing my name spelt that strangely gives me the tics...

#

This story has been archived. Comments can no longer be posted.



 
Tableless layout Validate XHTML 1.0 Strict Validate CSS Powered by Xaraya