Documentation needs? How FLOSS Manuals Can Hel


Published on

Presented by: Janet Swisher and Anne Gentle

FLOSS Manuals is a community, tool provider, and website dedicated to creating free documentation for free software and related aspects of the free culture movement. The website removes barriers to contributing to documentation by combining a simple authoring interface with documentation-oriented content management and publishing tools. It supports both wide-open collaboration and editorial control by separating in-progress work in the "Write" area from published work in the "Read" area. The FLOSS Manuals community comprises over 1000 registered users who collectively have produced over 40 books, mostly in the last two years. The group has also developed and honed the "book sprint" process, in which a complete manual is written in a brief period of 2 to 5 days. Both the website and the community actively support translations, with no one language considered primary. Manuals can be remixed, combining chapters from different books to create a new book, and you can export to HTML or embed content on a website.

This presentation describes the features of FLOSS Manuals project that deliver these benefits, and discusses ways that free software projects can leverage them to create documentation.

Published in: Education
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • Biggest concerns: quality and completeness   Can you interact with it or the people writing it?  Experience: reading, browsing, searching, finding
  • Most programmers hate to write, and would rather do almost anything else.
  • This is a structural problem, so don't feel bad about it.
  • E.g., DocBook, LaTeX Structured, multiple outputs. But arcane mark-up syntax, and difficult to customize.
  • Unstructured, on-line only. Let's face it, motivation is a problem.   We focus on "good enough" tools.    
  • a community of people who are passionate about FOSS documentation. Members of other FOSS projects who write their docs on the site Community activists who want to help people do stuff with FOSS Translators who want more docs in their language Writers who want to foster better docs for FOSS   a writing community -- at least 1800 registered contributors on the site and 300 on Discuss mailing list    
  • a website implementation that supports: 
  • WYSILWYG authoring interface Storage in XHTML Index of "chapters", which enables remixing across "books" Chat (IRC connection) built in
  • Not just translating, but building community.
  • Books or smaller, interlocked documents?   Despite trend on web toward multiple independent, loosely connected documents, FLOSS Manuals contributors believe many topics deserve full books. Remix is a gesture toward the other, looser organizational model.
  • an open source tools project
  • Programs which perform this task are called objavi (pronounced "ob-YAH-vee", as if the J was a Y), after the Croatian word "objavi!" meaning "publish!". FLOSS Manuals books are written and stored as HTML, but are converted to PDF and other formats for printing, reading, or further processing.   We're on the second Objavi, written in 2009 by Douglas Bagnall for FLOSS Manuals with support from and Internews. It was extended to output epub documents with support from the Internet Archive.
  • The next generation of the FLOSS Manuals software will no longer be a single instance of a wiki, but a platform for collaborative authoring. With the exception of Booki, there is no software available for this practice. Some have tried wiki and CMS software and find its not easy. Wikis are for the asynchronous development of unstructured web content. CMS are for the management of web-structured online content. Booki is something new. The Booki interface is designed around the authors and their needs to write, to discuss their views, to seek assistance with partner writers, to translate or reuse content and to publish completed works. While rapid development of content is the core focus of Booki, using a platform like this you can take the time to write a book by yourself as well as collaborate to produce high quality content very quickly.
  • We'll ask you for your ideas, too.
  • You can write a book, sell it, and keep the proceeds.
  • Documentation needs? How FLOSS Manuals Can Hel

    1. 1. Documentation Needs? How FLOSS Manuals Can Help Janet Swisher Anne Gentle Texas Linux Fest April 10, 2010
    2. 2. Does your documentation suck? Flickr: Theresa Thompson
    3. 3. You're not alone . <ul><li>I find it incredibly hard to make sure that the users get the right information from the docs.  </li></ul><ul><li>  </li></ul><ul><li>On the one hand, it seems that there is already too much information as people miss things that are already in there. </li></ul><ul><li>  </li></ul><ul><li>On the other hand, there is always information that people are looking for, and that is not in the docs. </li></ul><ul><li>  </li></ul><ul><li>-- Gaël Varoquaux, developer, Mayavi2 project </li></ul>
    4. 4. You're not alone. <ul><li>You could burn through a big budget trying to be everything to all users.  </li></ul><ul><li>Pick your priorities. </li></ul>Flickr: alancleaver_2000
    5. 5. &quot;Documentation is hard.&quot; &quot;Let's go programming!&quot;
    6. 6. It's hard for programmers to take a user's perspective. Flickr:Yandle
    7. 7. Traditional FOSS doc tools are powerful, but hard for non-techies to use. Flickr: couragextoxlive
    8. 8. Wikis are easy to use but hard to manage for documentation. <ul><li>  </li></ul>
    9. 9. If only you could find ... <ul><li>... people who like writing documentation. </li></ul><ul><li>  </li></ul><ul><li>... tools that are easy to use and support multiple outputs. </li></ul>
    10. 10. FLOSS Manuals is
    11. 11. FLOSS Manuals is ...
    12. 12. ... reading ... <ul><li>a collection of books -- over 40 manuals on free software </li></ul><ul><li>  </li></ul>
    13. 13. ... collaborative writing and editing ...
    14. 14. ... translating ... <ul><li>Localized FLOSS Manuals sites: </li></ul><ul><ul><li>Farsi </li></ul></ul><ul><ul><li>Finnish </li></ul></ul><ul><ul><li>Dutch </li></ul></ul><ul><li>  </li></ul>Translations in progress in Spanish, Greek, German, Portuguese, Russian, Chinese, Arabic, Vietnamese ...
    15. 15. ... remixing and publishing.
    16. 16. FLOSS Manuals is <ul><ul><li>the invention of Adam Hyde's -- an artist who taught workshops about open source tools and was frustrated with the materials available </li></ul></ul><ul><ul><li>about three years old (site started in May 2007)  </li></ul></ul><ul><ul><li>a non-profit organization (FLOSS Manuals Stichting, incorporated in the Netherlands) </li></ul></ul>
    17. 17. Objavi <ul><li>Try it at  </li></ul><ul><li>Objavi is distributed under GPL 2+.  </li></ul><ul><li>The source is available via  </li></ul><ul><li> </li></ul>
    18. 18. Booki <ul><li> </li></ul>
    19. 19. We also like to do book sprints. <ul><li>July 2008: Inkscape, Paris </li></ul><ul><li>Aug 2008: OLPC/SugarLabs, Austin </li></ul><ul><li>Nov 2008: Internet Censorship, upstate New York </li></ul><ul><li>Feb 2009: Digital Foundations, NYC </li></ul><ul><li>Mar 2009: Firefox, Palm Springs </li></ul><ul><li>Mar 2009: Introduction to the Command Line, Boston </li></ul><ul><li>Apr 2009: PureData, NYC & Berlin </li></ul><ul><li>May 2009: CiviCRM, Truckee, CA </li></ul><ul><li>Dec 2009: Etoys, virtual </li></ul><ul><li>Jan 2010: Collaboration, Berlin </li></ul><ul><li>April 2010: Mifos, virtual </li></ul>
    20. 20. How can FLOSS Man uals help your project? <ul><li>  </li></ul><ul><li>We have ideas. </li></ul>
    21. 21. Use the FLOSS Manuals tools to write your docs. <ul><li>  </li></ul><ul><li> </li></ul><ul><li> (alpha, ask via email first) </li></ul>
    22. 22. Join the FLOSS Manuals community. <ul><li> </li></ul>
    23. 23. Throw a book sprint. <ul><li>We've written how-to books about FLOSS Manuals and book sprints .  </li></ul><ul><li>  </li></ul><ul><li>We write manuals, after all.  </li></ul>
    24. 24. See FLOSS Manuals in action <ul><li>Mini-sprint for Firefox 3.6 </li></ul><ul><li>Tomorrow, Sunday April 11th </li></ul><ul><li>11 am to 4 pm </li></ul><ul><li>Genuine Joe Coffeehouse, 2001 West Anderson Lane </li></ul><ul><li>  </li></ul><ul><li>Other sprinters also welcome!  </li></ul>
    25. 25. Thanks! Discuss! <ul><li>Janet Swisher: </li></ul><ul><li>Anne Gentle: </li></ul><ul><li>FLOSS Manuals: </li></ul>