FLOSS Manuals: Too Good to Be Free - Notes

FLOSS Manuals: Too Good to Be Free By: Scott Nesbitt 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. He's a digital artist. But like many people in the FOSS world, he started FLOSS Manuals to scratch a particular itch. © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 1

Over the years, Hyde ran independent radio stations in New interest in technology. Zealand and managed ISPs in Australia and the A number of contributors are professional technical writers – Netherlands. Because he had little or no budget, Hyde the most best-known of that group are Anne Gentle and turned to free and Open Source software to help him in his Janet Swisher (both of whom work for Open Source work. Later on, to earn a living, Hyde ran workshops on free companies). That said, a majority of the professional and open source software – specifically software related to technical writers I've spoken to are contemptuous of FOSS streaming media. That's when he started developing documentation tools and techniques. documentation for the workshop participants. A good number of the contributors to FLOSS Manuals are Logically, he turned to the official documentation for the involved in FOSS projects. FLOSS Manuals has worked with software he was teaching as a starting point. He found, the Mozilla Foundation, the Free Software Foundation, the though, that: group behind the OLPC and Sugar Labs to write manuals. [T]he state of documentation for free software was pretty The reasons why people get involved are as varied. Some appalling. So, I went from documenting my workshops to see the advantages to writing free documentation. Others putting those documents on the Internet to adding more want to give back to the FOSS world. and more to it. One person told me an interesting story about how he got Hyde put the documentation that he wrote on a wiki to better involved: manage it. From there, Hyde decided that it would be more beneficial to have the wider FOSS community be able to add During the Mozilla Summit in Whistler (British Columbia), to and improve what he'd started writing, and to add more some good soul watched me sawing at my new Ubuntu documentation to fill in the various gaps in the FOSS world. notebook. After telling him the whole sad story (...of a To that end, Hyde registered FLOSS Manuals as a non-profit Windows user trying for years to climb the Unix organization and officially launched it in October, 2007. mountain...) he gave me THE GNU/LINUX COMMAND LINE manual, hinting that it's no big deal, half a dozen Who's involved? FLOSS dudes have put it together in a day or two. I need somehow to repay the gift. An interesting mix of people. All of them are, of course, The project is able to draw on a variety individuals to pull a FOSS enthusiasts. There are artists and software project together – subject matter experts, users, and developers. People with a casual (or more than casual) professional writers. Unlike corporate documentation, or © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 2

even many FOSS projects, FLOSS Manuals collects a Writing has been stuck in this terrible, romantic format of broader range of contributors and voices. With the manuals, the lone writer. Writing is a social process. How many you get people with varying levels of skill and knowledge times have you heard people say I was commissioned to who share their experience and insights. 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 Collaboration and community other people with the same interests, they have a ball and they write a book. And that's the advantage that FLOSS Manuals (and other Of course, getting people together has its hazards -- but not FOSS documentation project) have: they leverage a necessarily in the way that you'd think. When you get people community to gain fresh perspectives on a topic. I continually together who are passionate about something, give them a say that the people who use software can have insights into comfortable environment in which to work, and all they have that software which are as valid as those of developers or to do is work then all they'll do is work. professional technical writers. On top of that, FLOSS Manuals seems to promote a less formal or stiff style of Growth writing. It's friendlier to the reader. FOSS is as much about community and collaboration as it is Starting from Hyde's initial documentation, FLOSS Manuals about software. That goes not just for coding, but for has grown to encompass 51 manuals (and counting). A documentation as well. With a community, you're able to majority of the books cover FOSS applications like draw on a lot of expertise and numerous points of view. OpenOffice.org, Firefox, Inkscape, Audacity, and Blender. Theoretically, that should result in a superior product – There is also a comprehensive set of manuals for the XO whether that product is software or documentation. laptop and a book covering the Linux command line. As much as putting out quality documentation, Hyde is The manuals aren't limited to software, though. There are interested in building a community around FLOSS Manuals. ones that cover topics that are important to members of the A major reason is sustainability. Having a community that FOSS world. Like what? There are manuals covering how to FLOSS Manuals can draw from to maintain the circumvent Internet censorship, how to mentor students documentation increases the lifespan of that documentation. involved in the Google Summer of Code, as well as ones that give an overview of FLOSS Manuals and of the book Why do it that way? As Hyde told me: sprint process. © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 3

How FLOSS Manuals works 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 Everything – reading the manuals, writing them, adding to Make a PDF button. On top of that, you can comment on a them – is done at the FLOSS Manuals Web site. You section by clicking the Discussion link at the top of each wouldn't know it by looking at the site, but it's a wiki. A page. So even if you're not a registered contributor, you can heavily-customized implementation of the Twiki wiki engine. actually take part in the project. A posting good comment is The decision to use a wiki was a simple one to make. Hyde just as important as writing or editing a section of a manual. looked at a number of Open Source content management Writing, too, is obvious. That includes not only creating new systems and none of them packed the features that FLOSS content, but editing or updating existing manuals. While the Manuals needed – things like collaborative writing, credit FLOSS Manuals site is a wiki, you don't have to worry about tracking, and indexing. A wiki does, and Twiki also has a learning wiki markup. Everything is WYSIWYG. If you've number of plugins that allow users to expand the features used a Web-based word processor like Google Docs or Zoho and functions of their wikis. To fill in any gaps, the Writer, then the interface will be familiar. All you need to do developers working on FLOSS Manuals also created a is start writing and apply formatting from the toolbar. number of plugins. These plugins are available in the Twiki repository. The most interesting feature of FLOSS Manuals is the ability to remix content. Essentially, you can pick, choose, and To use the FLOSS Manuals site, you need to register for an publish the information you want in a custom manual. From account. This isn't a security or validation measure. It's so there, you can generate a PDF file, a set of HTML files, or that FLOSS Manuals can assign a copyright to you. you can get a widget that you can embed on a Web page or blog. Read, write, and remix I've put together a short screencast that shows how the There are three activities that you can carry out at the remix feature works. FLOSS Manuals site: reading, writing, and remixing. You can read and write manuals (there's no remix feature Reading is obvious: just choose the manual you want to yet), and you can publish them in the following formats: read and go from there. You're not presented with a long Web page, though. Even online the manuals are broken •PDF down into discrete chapters and sections. You don't have to •epub © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 4

•ODT usable. So much so that people are already using it to write books and the folks behind the FLOSS Manuals project have •HTML begun importing books from the FLOSS Manuals Web site When you publish from FLOSS Manuals, you can choose into Booki. On top of that, there's been at least one book from 25 pre-set book sizes or specify custom page sizes and sprint. Successfully, I might add. margins. If you want to follow the development of Booki, read the The results look quite good. Which plays into the aesthetic project's blog. strategy of FLOSS Manuals. I'll be discussing that in a few minutes. Looks can matter Documentation is often seen as being functional. Whether Moving to Booki from the commercial or FOSS worlds, manuals are in many A couple of years ago, the Twiki project forked – Twiki's cases kind of plain. But FLOSS Manuals also puts some creator took it commercial, and there is at least one Open emphasis on the aesthetics of manuals. Source variant called Foswiki. That fork caused Hyde and his Adam Hyde had this to say: team to re-evaluate their technical strategy and to consider rebuilding the FLOSS Manuals code base from the ground Documentation has to have an aesthetic strategy. up. Documentation has to be consumable. It has to be friendly, not just in the way it's written but in the way it The result is Booki. Booki is described as being like a wiki, presents itself. It should be easy to read. It should look but instead of getting a Web page you end up with a book. attractive. It should look like something you want to On the surface, Booki is almost identical to the current engage with. FLOSS Manuals site. You can read and write manuals FLOSS Manuals publishes many of its works at a print-on- (there's no remix feature yet), and you can publish them in demand site called Lulu.com. The proceeds from the sales of the same formats as at the FLOSS Manuals site. the printed manuals support the project. The printed books You can also import books from Archive.org, WikiBooks, and are very smooth – well typeset and laid out. The chapters FLOSS Manuals (as well as epub files) into Booki. dovetail into each other. There a real consistency in the terminology used, and there's a real flow to the books. 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 FLOSS Manuals also has a portable book binder. That © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 5

enables them to go to events, generate and print off books, or less. Hyde got the idea from Thomas Krag, who put and then bind them on the spot. It's a great promotional idea, together a group of people to write the book Wireless and a lot faster and a lot cheaper than going through a print- Networking in the Developing World. When the two men on-demand service. On top of that, it's quite interesting to discussed the process, Hyde saw how it could be very useful watch a book being bound before your eyes. to form content communities around specific topics and specific software. It's not only the manuals, but also the FLOSS Manuals Web site itself. Remember that the FLOSS Manuals site is a wiki. You can break the book sprint process down into these The problem with documentation that’s delivered using a wiki steps: is that it looks like it’s being delivered using a wiki. While •Come up with an idea for a book useful, wikis (at least out of the box) aren’t all that aesthetically pleasing. They’re functional, but they can also •Find a location be cluttered. •Get participants I think you know what I mean: navigation on the top, blocks •Get funding of menus on the sides, various bits of information in the footers. I don't know about you, but I find that distracting. •Front-load on content (if possible) FLOSS Manuals tries to remove as much of that clutter as •Start writing possible. The site has been heavily skinned and the interface Each book sprint involves gathering a group of people in one made quite minimal. You only get what you need. And that's location to write, edit, and publish a manual in anywhere links to the books, navigation, and the text of the manuals. from two to five days. It's not just a matter of dropping people All of that's been done quite attractively, too – with a nice somewhere and getting them to write from scratch. There's a choice of colour scheme, icons, and fonts. The site's not too lot of up-front work done before the sprint. Often, the people hard on the eyes, which helps when you're reading! planning the sprint gather information on the subject of the book and create a structure for the document. That structure Sprinting to a manual – it's more of a table of contents or outline – is fluid, even during the sprint. FLOSS Manuals regularly holds events called book sprints to Then, everyone gets together for anywhere from two to five pull manuals together within a short period – usually a week days to write the manual. But you don't have to be there in © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 6

person to participate; most sprints have several people typos, and to smooth out any inconsistencies in terminology working remotely. FLOSS Manuals has an built-in IRC client and writing style. that allows remote participant to communicate with the main group of sprinters. Toronto Open Source Week 2010 A sprint is very hands-on; participant use the software while writing about it. For writers who've never used the software As you may or may not know, there was a two-day book before, it's a great chance to learn and share what they're sprint held at this year's Toronto Open Source Week. This learning. If writers are familiar with the software, chances are book sprint came about because: they'll learn something new as well as have a chance to 1.For the last two years, I've been promising Adam Hyde share their expertise. that I'd take a more active part in a book sprint During a sprint there are regular breaks to check on 2.I thought that this would be a neat event to hold at everyone's progress and assign new tasks. Everyone is Toronto Open Source Week encouraged to take breaks to clear their head and get some air. And, of course, to get something to eat. During a number 3.This would be the first FLOSS Manuals event held in of book sprints, Hyde found that it was often difficult to get Toronto (and I think all of Canada) people to take those breaks. They were so absorbed in what The goal was to complete a manual for the Mozilla they were doing that he just let them continue. Thunderbird email client. I co-ordinated the book sprint from At the end of the sprint, you obviously wind up with a book. Toronto, and Adam Hyde took overall control from Berlin With longer sprints, the last day is usually quite hectic with (where he lives). people racing to finish content and to edit what's been The sprint was also fortunate to have seven students from written. Once time is called, somebody (usually Adam Hyde) Seneca College's Technical Communication program pushes a button to publish the new book on the FLOSS involved, along with a graduate of the program who's also Manuals site. With some books, FLOSS Manuals also former co-worker of mine. A developer who contacted me uploads a PDF to a print-on-demand service called also joined in. Lulu.com. You can download a very nicely formatted PDF version of the manual, or order a printed copy. Blake Winton from the Mozilla Messaging team in Toronto was on hand the second day to answer all of our questions. Even after the manual is published, it goes through an Several people from the Mozilla Messaging Team in editing cycle. This is to tighten up the writing, eliminate any © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 7

Vancouver also took part remotely, and their input and with IBM. insights were invaluable. Once everyone started filtering in, a lot of writing started In all, around 20 people were involved either on site or getting done. It was around that time that the folks in remotely. Not everyone was writing. A number of people Vancouver were coming online so that really helped. were editing and proofreading the book, too. That's pretty Adam Hyde was constantly spamming me with helpful advice impressive. and hints via email, and we were using the IRC client built [A quick aside: I'd like to thank: Chris Tyler, one of the into the FLOSS Manuals editing interface to communicate organizers of Toronto Open Source Week and of FSOSS, for with everyone working remotely. generously arranging space and equipment for the sprint; The goal for day one was to have 80% of the content Beth Agnew, who co-ordinates Seneca's Technical finished. That's what happened, more or less. Not a bad Communication program, for helping find student who were day's work. interested in taking part in the sprint; everyone who took part in the sprint, both in person and remotely; and everyone from Day two started off pretty much the same way. Three of us the Mozilla Foundation for offering support and pitching in.] 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 The manual was started by a technical writer with Mozilla new chapters were added and some of the people working Messaging named Jennifer Zickerman. We weren't starting remotely added a lot of content. from scratch, but there was still a lot to do. The goal for day two was to complete the last 20% of the In the weeks leading up to the sprint, I worked with Adam content, then do editing and cleanup. We were supposed to Hyde and some people from the Mozilla Foundation to nail down tools at 1:00 p.m. but I let that slide by half an hour or down what needed to be done. I also co-ordinated with Beth so. Agnew at Seneca to find and brief the students I mentioned earlier. We got to the editing and cleanup, with everyone taking a look at chapters and sections that they didn't work on. The first day of the sprint started off a bit slowly. There were Editing and cleanup can be as difficult as writing, but it's also three of us on site, and it took us a little while to get our very rewarding. And very necessary. Rewarding in that you footing. On top of that, a bulk of our team would be coming can really see the final product taking shape. Necessary in later. The Seneca students were attending a special because you catch all the silly (and not so silly) errors that seminar to prepare them for interviews for co-op positions slip in when you're writing in a hurry. © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 8

A few thoughts on the sprint making things perfect. Writers are like that; we try to write everything perfectly the first time. In a situation like this, It wasn't easy, but it was fun. At the end of the first day, my quantity trumps quality. thought was How does Adam Hyde do this without going crazy? Running a sprint isn't easy. 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 What's interesting is that I threw everyone into a situation everyone. that many professional technical writers would have trouble coping with – rapidly writing in a collaborative environment. I Overall, I think we did a good job. Could things have been have to say that everyone coped admirably. better? Sure. Could they have been worse? Definitely. But in the end, we achieved the goal. All that's left now is some fine Remember when I mentioned earlier that in a sprint it's hard tuning. 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 Everyone who took part in the book sprint can and should be all kept typing away. proud of what they did. Every contribution, no matter how small, made a difference. When you're writing online, it's hard to know how much progress you're making. So every few hours, I published a PDF version of the manual and let everyone know how many Some closing thoughts pages we had. That can be a great motivator – for example, we had 95 pages at noon and 115 pages at 2:00 p.m. shows In both the FOSS and commercial software worlds, the focus actual progress. of development is mainly on the software. Documentation is often an afterthought. But good documentation plays a role We ran into a few glitches. There was occasional trouble in the success of a software project. It guides (or, at least, with the wireless Internet connection; that's to be expected should guide) users from the stages of stumbling in the dark with a network being used by a large number of people. And with a unfamiliar application to the point of mastery. At the at one point on the first day, the FLOSS Manuals server very least, it should put them on that road to mastery. 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, Sadly, a lot of documentation in both spheres doesn't do which was a bit frustrating. that. Either because it doesn't exist, or it doesn't cover the information that users need. The FLOSS Manuals project I wasn't able to get across to the participants that they occupies an interesting niche in the FOSS world. And it fills a needed to write quickly; they didn't need to worry about © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 9

a need – a need for quality free documentation for free software. Contact Us The project tries to create documentation that focuses on what users need to know. It might not always succeed, but the successes outweigh the failures. Those successes stem from the range of voices that contribute to FLOSS Manuals. The books are constantly used, scrutinized, discussed, and updated. As all documentation should be. Web site: Remember that anyone can contribute to FLOSS Manuals. http://www.dmncommunications.com Even if you don't think you can write, you probably have Email: something to contribute – one or more tips or tricks, an update to an existing manual or procedure, an edit or info@dmncommunications.com correction. A little goes a long way. By contributing whatever Blog: effort you can, you're not only furthering the cause of quality free documentation for free software, but also furthering the http://www.dmncommunications/com/weblog adoption of free and Open Source software. Podcast: Who knows: maybe you'll be making a difference by taking http://podcast.dmncommunications.com part in a future book sprint! Twitter feed: http://twitter.com/dmnguys © 2010 DMN Communications FLOSS Manuals: Too Good to Be Free - 10

FLOSS Manuals: Too Good to Be Free - Notes

by DMN Communications

Accessibility

Categories

Upload Details

Usage Rights

2 Embeds 22

Statistics

FLOSS Manuals: Too Good to Be Free - Notes Presentation Transcript

http://www.dmncommunications.com	21
http://us-w1.rockmelt.com	1