Book Sprints and the importance of High Quality Technical Documentation
facilitated by Adam Hyde notes taken by Ben Connelly
This session explored how to do a book sprint using http://booki.cc.
- 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.
- 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.)
- 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.
- 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!
- 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!