Book Sprints and the importance of High Quality Technical Documentation

From DevSummit
Revision as of 17:57, 5 May 2015 by Vivian (talk | contribs) (1 revision imported)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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!