FLOSS Manuals interview for the Puget Sound STC chapter newsletter

Robert Reynolds contacted me requesting an interview for the STC Puget Sound chapter newsletter. It was published in PDF form, Writing for Free/Libre Open Source Software, but with permission, I’m using it for a blog entry as well. Thanks again, Robert!

Writing for Free/Libre Open Source Software

By Robert Reynolds

When Tomas Krag needed a book on setting up wireless written in a short period of time, he compiled a list of smart friends, secured enough funding to buy a stack of plane tickets and also to pay friends of friends to vacate a London flat for everyone to squat in. Following a week of hashing out details, determining the writing scope, and developing an outline, everyone returned home with their writing assignments and within three months, the first edition was ready. That’s what’s known as a book sprint—the concept that Krag coinvented— when a bunch of smart people gather for a week to collaborate on a book. Also known as collaborative authoring, this concept has now been around for a few years.

The FLOSS acronym stands for Free/Libre and Open Source Software, so it refers to both free software and Open Source software (“Free Manuals for Free Software” is one of their mottos). In constructing the acronym, the Spanish word libre was included to emphasize the idea of liberty—the lack of boundaries—as opposed to the notion of something that is available free of cost. Through book sprints, FLOSS manuals and other high quality manuals are developed in a short amount of time, and the Web makes it possible for writers from all over the globe to get involved remotely, if not locally. I interviewed Anne Gentle about FLOSS, its usefulness, and its implications for the technical writing industry. She is a senior technical writer at Advanced Solutions International, which provides management software for professional and social organizations such as STC. She also authored a book (Conversation and Community: The Social Web for Documentation) and maintains a blog (JustWriteClick.com).

Robert: How did you get involved in FLOSS? was it an epiphany, or the result of open source work you did?

Anne: I heard about the need for writers for the One Laptop per Child project through Bill Gearhart who sent out a call to help to writers he knew, right before the first major release of the little XO laptop. I had worked for Bill at BMC Software and was intrigued about writing for open source projects, especially since I could see wikis were involved. As a parent to two sons under the age of five, I was immediately interested in the OLPC mission of bringing durable laptops to children around the world. FLOSS Manuals founder Adam Hyde approached SJ Klein, community content director for OLPC, at Wikimania in 2007 and that forged the relationship to document the XO laptop and Sugar education platform using FLOSS Manuals tools.

Robert: What are the long term implications from a technical writer’s perspective? What are the economic implications?

Anne: Open source success stories are everywhere, with Apache web server the quickest to come to mind and the easiest, most visible outcome for a lay person to grasp. Open source has so many projects with or without compelling stories though. Perhaps the software was built to fill a small need, and ordinary people may say “so what.” With either resulting uptake and popularity of a project, open source has introduced a new way of thinking about building software and along with the new ways of building software come new ways of thinking about content – either the content that usually ccompanies software or the content that fills a need at a particular point in time. From a technical writer’s perspective, the ideas of sharing content,
gathering a community with a common goal of creating content, and giving away content are brand new and somewhat intimidating at first. Those ideas are reinventing our careers as we know it. Writing in isolation contains less value for some projects. This value change represents the shift for technical writers – both in the short term and in the long term, I believe.

Economic payments are changing from monetary to payments of attention, links, reputation, belonging, and other measurements of value that don’t really have a dollar amount tied to them. By claiming this shift in payment will happen, I don’t mean that technical writer’s won’t be paid, but I do mean that a technical writer’s value will be measured in more than just dollars or in return on investment in business terms. Your reach and influence may be valuable. Your reputation may be valuable. These areas are implications that I explore in my book, Conversation and Community: The Social Web for Documentation.

Robert: What are the advantages of the FLOSS method, other than the quick production cycle?

Anne: The quick production cycle of a book sprint is the result of weeks of planning and perhaps because content already existed that can be improved upon or “curated” into a more helpful collection than it is today. However, that advantage is the direct result of longer investment in background work. Other advantages include the basic rewards that people pursue by being part of an online community – your content can carry a reputation through attribution, be shared more freely, and gain attention through the event of the book sprint itself.

Another good explanation of the advantages of open methods for documentation come from the FLOSS Manuals FAQ:

“when you use free/libre/open-source manuals, you have the right to use, modify and share the documentation freely. Manuals on the FLOSS Manuals site are no-cost to use online. For paper copies, we charge just for the paper and printing, and a little extra to support making more books. You can also take the online version as a PDF file and print it yourself. You can also edit the documents on the site, for example, if you find things are incorrect, out of date, or incomplete. (You can also change your own copy, but we appreciate if you help us
make the manuals on the site better.)”

Robert: What are the drawbacks? too many writing styles? Does an editor monitor/assimilate the work?

Anne: There would be drawbacks to writing content only through book sprints, and it is not easy to get quality content written with one voice during that one-week sprint. Often we’ll hire an editor for the week of the book sprint to help writers write better, organize better, and get the big picture. These editors are not the typical grammarian and style guide police types though. They are editors who can ask the tough questions and challenge the book sprint team to improve even when the going gets tough. Book sprints force decisions about documentation that may lead to conflict even during the week of a sprint. Collaborative authoring is not easy and some professional writers haven’t had to collaborate well in the workplace yet. A skilled editor and book sprint facilitator can arbitrate and help the team produce a higher quality book in the end.

Robert: What are typical contents and audiences of FLOSS manuals? Highly technical stuff for geek folks? Will it eventually evolve to more simpler content for lay audiences (like our parents)?

Anne: That’s a great question – before writing FLOSS Manuals book (or any set of content) it’s important to analyze the audience. One example of a book written to bring technical content to any audience is the book
titled, The GNU/Linux Command Line: An Introduction. There have been many books written about the command line, but one participant even said:

“I have written basic introductions to the command line in three different technical books on GNU/Linux and read dozens of others. FLOSS Manual’s “Introduction to the Command Line” is at least as clear, complete, and accurate as any I’ve read or written. But while there are countless correct reference works on the subject, FLOSS’s book speaks to an audience of absolute beginners more effectively, and is ultimately more useful, than any other I have seen.”

So the book projects themselves are carefully chosen and audience analysis occurs before a proposed book is even started. The only requirement to have a book created in the FLOSS Manuals system is that it is about free software. We try to write in a friendly, accessible style.

Robert: Can you talk about any future plans for FLOSS?

Anne: Currently the main project for FLOSS Manuals is to develop an open source software product for collaborative authoring and publishing called Booki. We are planning to work with Archive.org on its development and it is in the very early stages of development. Using the lessons we’ve learned from our 14 book sprints to date, the platform would enable collaborative publishing as well as let anyone install and maintain their own installation. The FLOSS Manuals tool used today is a modified TWiki installation uses extensions that are given back to the TWiki community. It is all free software. However, it does require user support and the overall site may not be easily replicated. The Booki project starts from the beginning, developing the wiki and chat tools we’ve found useful.

Robert: Tell me more about the book sprints. Would this be a volunteer opportunity for STC members to gain more writing experience, network, etc.?

Anne: Absolutely. At DocTrain West last year, we had participants work on a Firefox manual and the chief engineer from Mozilla came to the event to participate. That book has been helpful to many people and that sprint also enabled 14 remote collaborators to make contributions within the timeframe of the sprint. Students, writers in other
countries, unemployed writers, you name it, all could benefit from participating in the FLOSS Manuals community. In-person networking occurs at the sprints themselves, which may be in all areas of the
world. Networking and connections can also happen on the FLOSS Manuals Discuss mailing list. Go to
http://lists.flossmanuals.net/listinfo.cgi/discuss-flossmanuals.net to sign up or read archives.

Robert: Have you ever been approached or would you (FLOSS) ever consider working with non-open source companies to produce manuals? (This would obviously go against the open source model…).

Anne: Companies have asked to use the FLOSS Manuals tool set for authoring, but the basic goal of FLOSS Manuals is to provide free content for
free software. If the software or project being documented doesn’t meet the criteria, a book isn’t set up in FLOSS Manuals. You could use any tool such as FrameMaker for shortened manual production. For example, IBM uses an in-person collaboration approach to authoring RedBooks. They bring together a team of subject matter experts for a short period of time to work on the outline and some of the content,
then they finish their “writing assignments” within a short time period such as 4-6 weeks.

Robert: Would you consider selling or licensing the FLOSS collaborative publishing platform to non-open source companies?

Anne: The Booki platform being built will be available through an open source license, in hopes to bring more collaborative publishing options to more documentation projects.

It’s an exciting time of growth for FLOSS Manuals – thanks for asking these great questions.

Writing for Free/Libre Open Source Software
By Robert Reynolds


  • December 11, 2009 - 9:16 am | Permalink

    I work on documentation projects for commercial software products, in which we’ve been adapting to new development methodologies like Agile. Rather than developing the whole product (and its documentation) at once, Agile uses short “sprints” to develop the product in stages. These short stages seem to have a lot in common with the FLOSS methodology.

    I’m reading with keen interest about the methodology you use. I think that some of things you’ve learned can help us with the challenges we face when working in Agile — for example how to edit the docs thoroughly and consistently when they’re being developed piecemeal.

    One other thing: you mentioned the IBM Redbooks model. That’s an apt comparison, but it’s imperfect because it’s based on having a stable, complete product; whereas the new methodologies will need to work in environments where the products are being built simultaneously with the documentation.

    Thanks for doing this interview, Anne, and for the other things you’ve written about FLOSS manuals in your book and your blog. They’re very informative, and I’m excited about the possibilities of adapting the FLOSS experience to my projects.

  • Pingback:   Weekly links roundup by Communications from DMN

  • Leave a Reply