Book Sprints and the importance of High Quality Technical Documentation

From DevSummit
Jump to navigation Jump to search

facilitated by Adam Hyde notes taken by Ben Connelly

This session explored how to do a book sprint using http://booki.cc.

Adam's Story

  • Background in nonprofit traveling and training.
  • Six years in wireless infrastructure projects.
  • Started wanting to document the procedures for what he was doing, but also feeling burnt out and short on time, so wanted to do it in one week!
  • Started with Table of Contents for a paid technical edition
  • It started to take a life of its own and was eventually joined by the Linux doc project guy who developed the One Week to Done idea and added some additional tools to the project.
  • He has now helped manage projects to write 38 books.

First steps

  • Could this be used in education? How about other fields?

Assembling the right people

  • The people assembled have to have comprehensive coverage of the topic between them.
  • You need people who can write!
  • There must be a somewhat similar approach to the concepts for it to be functional.
  • To decide what ultimately goes in and what doesn't, somebody needs to be a good facilitator. (You might also end up leaving out topics nobody wants to write about.)

Funding models

  • Will you have volunteers or paid authors? Paid illustrators?
  • Marketplace model (teachers paying teachers)
  • Print copies of Adam's books were sold via Lulu.
  • Ebook or print?
  • Booki also functions as a marketplace.
  • Other examples of models are sourcefabric.org and FLOSS Manuals.

Why do a book sprint?

  • Why not do a mediawiki?
  • A T.O.C. functions like a wiki but in the structure of a book.
  • Tracking changes for licensing is important.
  • The concept of a book is different from the concept of a wiki.
  • A book is structured end to end, and lets you drag and drop chapters into a publishing engine.
  • For a single author, you don't need to work online in a browser. You can use desktop software like Scrivener (or Literature and Latte).
  • When you're working with multiple authors, you need a workflow system. This lets you see what's done, what's left to be done, and use project management tools.
  • A book sprint can download onto a USB drive, be downloaded as a PDF, and you can have a PRINT edition!
  • It also lets you save different editions of the same book or manual and have different translations.
  • It gets you over the hurdle of documenting.
  • Testing and continual learning are not really a part of these tools already.
  • Ideally, during the week of the sprint, only the people in the room have access to it.
  • Having the firm deadline of a week gives people a lot of motivation - the idea that at the end of the week, if it's done we can publish it. If not than we won't.
  • Another advantage is these books can be distributed in ways that get around internet censorship in some countries (print or physical electronic files).
  • You can also have proofreaders working remotely.

Conclusions

  • When people think of creating a book, you assume it has to take years and lots of pain, but when you collaborate in this way, it's done in a week and is lots of fun! It's like magic how well it works!
  • It also shows that more and more things that were traditionally done solo can be done more effectively in collaboration.
  • Adam really likes the "remixability" factor that you get.
  • It's absolutely critical to have a facilitator that makes the project management aspects work.
  • Raising the bar!
  • Tangibility!
  • One thing to determine ahead of time is how copyrights will work with multiple authors.
    • Will the copyright for the whole book be held jointly?
    • Different authors hold copyrights on different chapters?
    • What if you're selling the book? How will the proceeds be split?
  • Booktype from Sourcefabric has free and open source software roots. It only works with CC or GPL type licenses.
  • The whole thing works because it's a democratic model.
  • The good news is, funders seem to like it too!