Dear QA-self from the past,
This is your QA-self from the future writing to give you a quick pep-talk. Right now you do not have access to the Website’s Database so information that could take you a matter of moments to obtain end up taking way longer because you don’t have permissions to a run a simple query. You also have no control over your Test Environment or what gets deployed to Production. You’re frustrated because changes you aren’t aware of keep sneaking in. The good news is that things will be opening up in the coming years when you start working on Safari Flow. You’ll have access to your Website’s Database and can deploy builds yourself to the Test and Production Environments as needed.
To some, November brings to mind the beginning of holiday cooking season, with massive feasts, multiple dishes, a neverending list of ingredients to buy at the grocery store, and possibly a house full of visitors who want to be useful but usually just get in the way. To others, November is the month of NanoWriMo, a ritual amongst amateur writers to shut yourself away for a month and crank out that novel that you’ve always wanted to write (usually poorly, and usually alone). At Safari Books Online, we went into November engaging in our own mammoth writing exercise, with its own massive list of things to do and its own eager crew of contributors wanting to be helpful. This was our Book Sprint.
The challenge: describe an application that had evolved over time through the contributions of a dozen developers, where documentation had perennially lagged. It wasn’t a simple matter of asking one or two people to set aside two weeks to properly document their code, but to get a bunch of individuals who were each experts at different aspects of the application to sit together and pool their knowledge.
What we hoped would emerge: a comprehensive software manual that didn’t read like it was written by a crazy person. It was a very interesting challenge, so we approached Adam Hyde from BookSprints to help us focus our efforts.
A Book Sprint, as the name might imply, takes its name from a code sprint and is, in many ways, a method of taking agile software methodologies and applying them to the collaborative task of writing a book. We sat down with Adam and had him lead us through a discussion session where we started raising topics that needed to be discussed in the book. Each of the topics were all written down in a sticky-note, then posted on a whiteboard. Once posted, we grouped the notes into common themes, and as the groupings evolved, the a basic chapter-and-topic structure emerged. This was organized into a rough table of contents, and each of us picked out a few notes that we felt comfortable writing about, and we set to work putting down our thoughts into a collaborative online document which was the beginning of our book.
Replace the notes with tickets, the table of contents with a backlog list, and the periodic status checkups with a standup, and you can see how this authoring process mirrors the workflow of an agile software development team. Indeed, at its core, agile development is a process and mindset for organizing a group of talented and motivated individuals who are all contributing to a project that may evolve over time, and there’s nothing that says that this approach only applies to code.
Writing books can benefit from collaboration and must evolve as ideas and information emerge through the writing process. By switching out the conventional model of a rigid outline in favor of modular topic cards, multiple contributors can start writing independently—working on individual pieces of the book in parallel—then backfilling continuity and flow afterwards as part of integrating chapters together. If a new topic needs to be covered, treat it like another requirement, write up a post-it and stick it into the appropriate chapter.
Similarly, one could envision an agile kitchen where, rather than having a hierarchical set of chefs and sous chefs, a set of discrete tasks are put up on a whiteboard like: “mince garlic”, “boil potatoes”, or “brine turkey.” Individual contributors note the tasks that need to be done, pick them up as they are ready and then add new tasks as the evening evolves (“open another bottle of wine”)…
…this may or may not describe a standard dinner party between Safari employees.
We’re big fans of agile development at Safari, not because it’s a cool, hip thing to do in the world of software, but because we genuinely enjoy the human interactions that can emerge from deep, thoughtful, and genuine collaboration. There’s nothing that says that it has to be limited to “writing the codes.”
What did we have?
We use Chef for infrastructure management at Safari Books Online. We have a Production Chef (ChefProd) server that performs standard tasks such as putting users on machines and setting up monitoring. Chef cookbooks also perform specific tasks such as setting up web, database, and application servers. In addition to the Production Chef environment, we also have Chef Development (ChefDev) environment used for testing Chef cookbooks.
We run a Gitlab server for version control. Gitlab is the open source project for self hosted git management. It is a git server and web UI written in Ruby on Rails and it works great.
What did we want?
- Goal #1: No knifing in anything to production manually.
- This was for fat finger errors as well as a lack of version control backup.
- Goal #2: Everything in Chef was in version control.
- Goal #3: To have our entire Chef ecosystem within a testing framework.
How we did it.
We built a Jenkins VM (provisioning users and monitoring through Chef) for our CI (Continuous Integration) testing server. Jenkins is a great tool for testing out software.
Each Chef cookbook is stored in version control with Gitlab. For each git cookbook repository, we made an identical Jenkins job. This Jenkins job would run all the tests on the cookbook on one of its nodes, searching for bugs. We added a git hook on merge to master for each cookbook. This means every time one of us git committed and merged to master, Jenkins (who was always listening for the Gitlab hook) would fire off the cookbook test.
All this happened in the Chef Development (ChefDev) environment and we wanted to accomplish Goal #1, which was put tested code into production without using knife. We needed a way to push changes to production, the simpler, the better. We arrived at having a trigger file, i.e. a file that would send the signal that we wanted to push to production. If and only if this trigger file was git committed and merged to master, Jenkins would deploy to production. We decided to use a CHANGELOG file (with the added bonus of frictionless deploy comments) but any file would suffice.
With this system, we could test out cookbooks on the ChefDev environment, and have Jenkins knife them into production at will. All code was in version control and tested. This fulfilled Goal #1, Goal #2, and Goal #3.
Vagrant makes development better. We use the above workflow and leverage Vagrant VMs for local testing before this entire process. With new cookbook development, it’s nice to be able to move quickly into writing tests and software. This is where Vagrant shines! We made special Vagrant VMs that mimic our production environment. DevOps can test new cookbooks locally before creating Jenkins jobs and Gitlab hooks. Existing cookbooks can be tested locally before the Jenkins tests, so you can develop and iterate quickly when starting out on a new feature.
I had no idea what product management actually was, or if I was qualified to do it when I started a job hunt this time last year — a path that ultimately lead to me joining Safari as VP of Product in August 2012.
Modern tech product development is surprisingly poorly documented in books, so before I got on the plane, I turned to turned to Google and started pillaging information as quickly as I could about what product management means at the big Silicon Valley firms. Looking back now, it’s easy to see how my checkered career — producing 50+ websites for cash-strapped publishers in a hurry, and latterly as a failed entrepreneur in a cash-strapped analytics startup — had inadvertently given me many of the characteristics of a product manager. So for anyone wondering what Product Management means here at Safari I thought I’d share my crib-sheet here.
After making my way through the horror stories about Product interviews (comparable to the mythical “Oxbridge” university interviews in the UK) I started to find some great information on sites like Quora, Glassdoor, and a few blogs. Many of the interview horror stories are from Google, where analytical / mathematical thinking are combined with the hacker ethic. How many ping pong balls fit in a 747? How many piano tuners are there in Chicago? Luckily Google never replied to my application letter, but a post from a former Microsoft “Programme Manager” provided some helpful documentation about how to structure your thinking for an interview like that. I found it incredibly helpful in the circumstances.
Product management is about boiling things right down to the very essence of the problem you need to solve for your customer, and then sticking your neck out to prioritise and make the tough calls (hopefully supported by data) on how you get there quickest. It’s also about building and leading a team and putting them in the best situation to do better than you could ever do. Focus, discipline, and trade-offs. [Insert joke about how product managers can stop reading here]
The first documents I turned to were fairly epic posts written by a former Amazon engineer about what it’s like to pitch to Jeff Bezos. I recommend you read it and its follow up in full. The short version? Be succinct, be prepared to articulate yourself fully in writing (rather than powerpoint), and internalize the icky-to-a-Brit but informative “leadership values” of the company. I would argue that they make better products in a more disciplined way than anyone else.
Amazon is undoubtedly a company that is on fire, executes ruthlessly on a clear strategy, and delivers wildly successful products. They have developed a remarkably simple and powerful approach to product development that I’ve stolen much of for Safari. They “work backwards” in tiny teams. This means starting the whole process off with the press release you’ll use to launch the product when it’s done. The (flawless) thinking is that if you can’t summarise your product/feature in a headline that makes people know exactly what you’ve done and why they want it, your product will lack focus and probably suck as well. Read more about working backwards from Amazon’s CTO, and on Quora.
Product management is all about discipline and decision-making, not groupthink or consensus. That means sticking your neck out. Another no-brainer idea I stole from my research was the idea of the “Directly Responsible Individual“, which I got from Apple.
At Apple any product, and product sub-task, has a DRI attached to it. The process works incredibly well. Every project has a cover sheet with a list of names on it next to a task. So everyone knows exactly who to turn to for doing X or Y. No task has two DRIs so there’s no ducking the blame. It’s surprisingly hard to do, but a great project manager (which is not the same as the product manager) will make sure those roles and responsibilities are assigned and understood.
Product vs. project
It’s worth talking about project vs product management. Some people confuse the two, and while great project managers can make great product managers they should never, ever be the same person on a project. The two have totally opposing, although complementary, priorities.
The product manager is focused on delivering something that will delight the user and deliver on the business requirements. The project manager is focused on getting a list of tasks done in time. I have spent a lot of time as a project manager, and while I have huge respect for PMs, I absolutely hate doing it. What product managers should learn from project management is the ability to prioritise ruthlessly, make never-ending tradeoffs, and swap out tasks on the fly — especially in an agile development environment.
Finally here’s a few of quotes I found that do a great job of boiling product development down:
“Any idiot can think of new product features. Only a great product manager can take them away.”
“If we haven’t got data, then we’ll use opinions instead. Starting with mine.”
“Perfection is achieved not when there is nothing left to add, but when there is nothing left to take away.”
“Take the single most important feature, do just that, and polish the hell out of the experience”
And some of the sources I leaned on heavily for my research:
- Ian Macallister on Amazon’s Product Development Process, at Quora
- Microsoft program management
- Joel on software:
- Cindy Alvarez’s 8 Non-Useless Interview Questions for Product Managers
- How to hire a product manager
It turns out that these tips on how to fake it have been incredibly useful to me in the last six months, so any further advice is most welcome.
Safari’s Content Team has the dubious distinction of having the highest volume of tickets in our company-wide issue management tracking system (we use Atlassian’s JIRA). We easily win this competition, with more than 1,500 open issues on any given day. But do we buckle under the psychic weight of all these tickets? Nah… go ahead, bring ‘em!
Why So Many, You May Ask?
The Content Team has quality-checked 12,729 brand new titles loaded onto Safari Books Online from April 2011 to last week. For the past 6 months, we averaged 753 titles/month, or 177 titles/week. We track only issues that are clearly errors (e.g., a title-cover image mismatch) or issues that seriously impact readability (e.g., all images are random color bitmaps like this one from a real book).
Each time we find an issue like this, we stop the title in the pipeline before it goes live, and follow up one way or another to correct it. We track all of these issues in JIRA, so we can manage the corrections and move each title live as quickly as possible.
At this time, we only check brand new titles, but our publishers are free to update titles at any time without oversight. And, since we only started quality-checking new titles in April 2011, but Safari launched way back in September 2001, there are quite a few titles that we haven’t scrutinized. Various problems get reported: the unavailability of practice files referred to in the text, teeny tiny images too small to make out, or broken links. An average of 200 new content issue tickets are created each month.
That explains where our issues are coming from. So, how do we manage them?
Standardization, Automation, and Elbow Grease
Well, managing these issues has been an evolving process. We are fortunate to have on staff not just one, but several JIRA experts, who are always willing to help us out with custom fields and productivity brainstorming.
We’ve been working our way up to several key improvements, which are now at a point where we are starting to realize the benefits. With >1,500 issues, global improvements don’t happen overnight. It’s easy to add new fields to help us organize and track issues, but then those fields need to be populated – a daunting task. And of course, in order for this system to work, everyone has to use it the same way — which means a bit of documentation, training, and oversight are needed. Here are the keys to managing this type of issue volume:
- Standardization: custom fields, boilerplate language
- Automation: QaQ, automated email
- Elbow Grease: Monthly issues export & follow up
- NEW: Greenhopper
Standardization. Custom JIRA fields help us slice and dice the issues into manageable groups. For example, we added a publisher field, which allows us to export all the open issues for a given publisher. We use a component field, which allows us to sort that publisher’s open issues by whether the issue relates to the source PDF, the source EPUB, the metadata, companion files, etc.
And we have boilerplated the language we use in certain fields, which serves two purposes. First, it saves the ticket writer time – she doesn’t have to consider how to explain a given issue, she can rather just copy/paste the explanatory text from our (constantly updated) JIRA Issue Map. Second, we make sure our boilerplate language is clear enough for publisher-facing communications, even if our primary publisher contact is a rights person who has no need to speak the lingo of CSS or toc.ncx, for example.
Automation. Our stellar engineering team has built us an QA Queue application (we call it the QaQ) to manage our daily load of new titles to quality-check, and this system hooks right into JIRA. After we check a publisher’s new batch of titles, we follow up via email to let the publisher know which titles are live, and which need a little more work before they can go live. The QaQ automates the creation of lovely formatted emails; for titles with associated JIRA tickets, it exports the text from key fields which detail the required fix in easy-to-understand language.
Elbow Grease. We are now rolling out a monthly export of issues for each publisher. When a publisher receives a spreadsheet listing their issues in detail, sorted by issue type, it’s a lot easier for them to follow up en masse, so they can get as many new titles live (or corrected, if they are already live) as quickly as possible. We did a pilot of this new process with a select set of publishers, with very promising results. We don’t want our publishing partners swimming in the JIRA sea, nor should we require them to rely on email alone for making sure all their titles are working well on Safari.
New: Greenhopper. This plug-in to JIRA has us really excited. We are doing a trial run with a Kanban workflow for the subset of Content issues requiring engineering work. In 2010, we were managing the long list of engineering Content issues via JIRA and email alone. Well, that doesn’t work so well once you have more than a handful of issues. So in 2012, we switched to a shared Google doc so we could be sure we were all working off the same songsheet. But even that has its shortcomings – we meant to keep notes in the Google doc and ALSO update each JIRA ticket as we worked. In theory. Often, only one or the other would get updated, and sometimes the priorities in the doc didn’t match the priorities in JIRA.
But with Greenhopper, we plan to kiss the Google spreadsheet goodbye, for the most part. We created a Kanban board with a few key buckets: Pending, In Progress, In SBO QA, and Completed. We are strictly limiting the number of In Progress tickets to 10. (If you go over 10 tickets In Progress, the whole board turns a distressing bloody red.) This way it’s very clear for engineering to know exactly what must be worked on. And the Kanban board is very easy to work with – in our status calls, we can discuss the entire board, and update each individual issue as we discuss it from the same board. No more getting lost in a sea of dozens of browser tabs or windows.
If this Greenhopper experiment works well for our Engineering tickets, we will explore creating boards for other types of Content Issues. The sky seems to be the limit in terms of how you structure your boards; they seem fully customizable based on the fields you want to use.
OK, now that we have these great tools in place and are starting to use them, we can start setting some nice aggressive goals to get our overall numbers down. (The team is going to kill me when they hear this.) Let’s beat our current created-to-resolved ratio by summer, guys!
TL;DR — Release products at conferences. The products will be better and you’ll be happier.
Test-driven development is a technique that helps programmers build large applications from small, working components. It has been successful enough to unlock developers’ innate love of acronyms, ranging from ATDD and BDD to MDD and UGG. TDD is important in the industry because it forces a mental shift inside the programmer’s mind. Like most humans, programmers are all too willing to succumb to really lame brain bugs. Instead of falling for the trap of designing and implementing a grand cathedral in one single volcano of brilliance, TDD focuses on a continuous stream of achievable, minor, functional bricks. Conference-driven development offers similar rewards for virtuous choices, but works for the whole product development team rather than just programmers.
Last year, my group decided to invest a certain amount (5%) of time to unstructured self-directed activities – we call it “investment time.” We do this on every other Friday afternoon.
This isn’t a new idea. The concept has been widely touted, and according to this post, it has been in vogue, or at least in use, as far back as 1948 (at 3M). There are also many well-documented flaws with this idea; see these comments. The comments on coding horror’s post are full of examples of how this can fail.
But there are good reasons to try: In a client-driven consulting organization, engineering work is tightly constrained: by feature requirements and/or by budget. Often it’s an engineer’s role to be the grownup on a project, reminding everyone about technical constraints that will lead to scope growth and cost overruns. It can be tiresome to always be the person that says “no,” and every now and then we need a chance to think expansively, try new things, and exercise our creative juices.
So the idea isn’t new, and 5% of our time isn’t really enough time to launch major new initiatives: gmail isn’t going to get invented every working other Friday afternoon. But I want to talk about this practice because I think it has had a lot of value for us, we’re a small organization without the resources of a Google or a Microsoft, and this gives us a different perspective. In these sessions, we have a chance to try out new things, to work with different people, and to think creatively, but it hasn’t necessarily been easy to realize these benefits. I’d like to reflect on how this has worked and not worked for us, and then I’ll describe what we did in our most recent session.
Since we started this six months ago, we’ve had mixed experiences. Sometimes interesting things that provide tangible benefits have happened. We built an XSLT code coverage tool and integrated into our unit tests. We worked through some incompatibilities in our core platform so we could deploy <a href=”http://newrelic.com”>NewRelic</a> to monitor it (which by the way has been a huge help). Other times people drift off and work on their regular work. A few times people have left early. My feeling is it’s OK that that happened because this is an experiment, but we do want to get the most out of the time we’re spending and so we try to learn from the failures as well as benefit the successes. Here’s a quick run-down on what seems to work and what doesn’t:
1. Celebrate success. OK this is just like mom and apple pie, but it’s easy to forget to do. We follow up each session with a report out to the whole company about what happened. It’s a good opportunity to let people know what the engineers are wasting their time on so they can see just how
useful it is.
2. Do it on a regular basis, at a predetermined time. This is really critical: it ensures that it will actually happen. The whole idea is to be open to new ideas, so you don’t know *what* you are going to do exactly, which lends a bit of an air of unreality to the whole enterprise. To combat that, you have to be very concrete and specific about when you are going to do it, who’s going to be involved, and where it will happen. Beer and food help too.
An important corollary is: no Friday releases. If you can make this part of your company culture, you will benefit regardless of whether you also have investment time. Friday releases are bad because nobody tests them until Monday except your customers – nuff said. But it’s especially important to keep releases away if you are trying to reserve some unscheduled time.
3. Have everybody in the same place together. This has been really important: the best weeks have seen a low hum of activity in the office, and significant exchanges have occurred from people spontaneously walking around the office and looking over other folks’ shoulders. However, one thing we need to get better at is involving our remote developers. There’s a tension around encouraging collaboration: some people work better alone; others in groups. We’re still learning the right balance.
4. Don’t force people to be creative if they don’t want to, or feel like they’re too busy. People shouldn’t be made to feel guilty if they’re not inventing a cure for cancer in their spare time.
Also, sometimes there is a monkey on someone’s back that they need to shake. Ideally this shouldn’t happen, but if it does, delaying work you really absolutely need to do just so you can take time out to come up with other freakin’ stuff to do obviously makes no sense.
5. Find a way to encourage everyone to generate good ideas in advance of the investment time. We’ve run an exercise with colored markers and sticky notes that was fun and generated all kinds of great ideas. Sometimes just going around the room and having everyone say what they’re planning to do
6. Add competition to the mix. From time to time we like to issue a programming challenge to the engineers at our company. This gets folks thinking about work in new and creative ways, and well – it’s fun. We
strove to build the fastest sudoku solver; we competed in robocode matches. Hilarity ensued: programming chops were rewarded.
The Connect4 Challenge
Recently one of our engineers, Mark LeMay, came up with the idea of a framework showdown. The idea was to learn more about different programming languages and web application frameworks by devising a simple problem, applying various tools to it, and comparing notes.
The problem we chose to work on was Connect Four. This is a simple two-player game, familiar to many. You drop disks into a 6×7 array of cells, where they fall to the bottom of their column with the object of getting four in a row of your color before your opponent does the same. It seemed ideal from the perspective of being easy to program, but would require some server side programming in order to manage the game state, since it must be shared by multiple players.
We came up with a scoring rubric for evaluating entrants that awarded points for everything from “return HTTP OK” to stress testing and unbeatable AI. Pretty ambitious for 4 hours on a Friday afternoon. Yes, well it turns out that 4 hours is not enough to learn a new language, and a new framework, and to code a perfect Connect4 AI that can run while being stress tested by North Korean hacker bots (actually we didn’t try that last one, but I’m pretty sure all the entrants would have failed it).
However, it is almost enough try out some new tools and get a feel for what it might be like to do some real work with them. Here are the ones we tried: Ruby on Rails, Grails, Google Web Toolkit, Node.js, Lux (XQuery), Go and Google Apps, Clojure, Wicket, and Django. Some newish stuff, a lot of stuff that is not super new, but this was an opportunity for folks who don’t get out that much to try out a newer, younger model, um as it were.
A few things people wanted to or suggested trying were but never got to were: Scala, ChicagoBoss/Erlang, and HapiJS. Maybe we’ll check them out later.
I’m not even going to attempt to give you a run-down on all these tools in this post, but in some later posts we’ll cover some of them (we’ve already heard from Robert Hall re: sockets in node.js).
As part of the PubFactory squad coming over to Safari Books Online, I had some idea of the code that SBO engineers wrote but I really wanted to see “how they were living.” What was it going to be like working in a Python/Django environment? I set off to figure it out. I cloned a pre-existing Safari Books Online repository and tried to run a project. Concepts were very familiar, which was good, but I was surprised by something: there was not a trace of IDE configuration in the repo at all. No hidden folders with project configuration, not even a mention of *.sublime-workspace in .gitignore. The PubFactory team primarily uses Java so the IDE (mostly Eclipse and a little IntelliJ) is a big deal.
Slightly confused, I asked Liza what IDE her engineers use and she literally laughed at me: “IDE?? You mean editor?” I didn’t mean editor, I meant IDE! I had heard of a resurgence of engineers using lightweight editors from the 70′s (emacs, vi/vim) and apparently I now worked with a bunch of those people. (Admittedly the word “hipster” did come to mind.)
I held this worldly bias until I had a Node app to build (more details in the upcoming days). When I sat down to write some code I said to myself, “You don’t really want to write Node in Eclipse do you, who does that?” I had Sublime Text 2 installed already so I gave it a go. Turns out writing server-side code in something that is actually fast was really nice. The soul-sucking 30 second Eclipse startup window just wasn’t there.
As a well-conditioned Java engineer I also started out relying heavily on Sublime’s code completion. I was initially cross when it wasn’t great but there are Sublime plugins to make it better and it doesn’t take long to realize you don’t really need it either. It was actually really nice to actually write the code as opposed to typing three letters, hitting ctrl+space and choosing your nugget of code from a list of options.
I went to a meetup a week after starting my Node app and heard about WebStorm — another hipster-friendly editor. It was publicized at the meetup as having a “really nice debugger.” In Java a working debugger is an absolute necessity, so I went to give WebStorm a shot. My first impressions were that the editor was interesting (Live Edit feature is neat) and as publicized the debugger is nice. But then I thought, “Do you actually want to pick an editor based on its debugger? You haven’t cared or needed it in the last ten hours.” Another IDE feature melting away.
The natural conclusion to this story is I have now realized the error of my ways and dumped everything for the 70′s technology (MacVim). I don’t think so. MacVim is missing some things, or I haven’t figured them out yet. I still miss the ability to search through all code in your project without using grep. I also haven’t quite gotten used to knowing where my code is yet (Eclipse makes that irrelevant with find a resource: cmd+shift+r).
I am currently in a halfway-house with Aptana Studio. It’s an Eclipse variant — I know — that feels much faster than the full Eclipse install, especially Juno. Aptana Studio has a built-in terminal so you don’t have to switch windows to see output, has useful git support, and lets me do all the Eclipse-y things I still care about. Apparently this process will take a little bit longer with me.
[Ed. To be fair, some of our developers do use Eclipse, even for Python, but not the majority. — Liza]
Question: How long does it take to write, produce, and print a book—and finalize all the standard e-formats?
A. 2 months
B. 4 months
C. 3 days
Granted, the answer obviously depends a lot on what type of book we’re talking about. It also depends on your definition of “finalized.” Up until last week, I’d have said Option A was possible, if the book had a lot of luck, a very determined author, and the best production team money can buy. Option B is more the norm, in my experience. But last week, I witnessed—and participated in—Option C, the 3 day book.
Last week I participated in a Book Sprint hosted by Google. It was facilitated by Adam Hyde, creator of the Book Sprint methodology, with Intro and Outro “unconference” workshops facilitated by Allen Gunn of Aspiration. You can find my daily impressions of the experience here.
I was glad to get the opportunity to participate, and I learned quite a bit from the Book Sprint experience. But what I learned was not exactly what I set out to learn. I expected to observe the Book Sprint process and be able to map it to traditional trade or academic publishing workflows. While that still seems entirely possible, I think I learned a bit more than that.
Critical benefits of in-person collaboration
The biggest concept I took away from the book sprint experience was the power of in-person collaboration. It’s hard to convey the importance of this if you don’t experience it for yourself. A group of subject matter experts and end users sitting together in a room talking things through produces amazing results. It’s not just that you’re cutting out all the time lag of email and phone tag. It’s the immediate exchange of ideas that quickly shapes and defines the concepts and the structure of the work. And when you’re focused on the book all day every day, without distractions, with the ability to ask questions and receive immediate answers, you stay in the zone. It’s a pretty amazing thing—and why limit this concept to Book Sprints?
Documentation is such a critical part of my Safari work, and I didn’t expect to think about that at all during the sprint, but I actually learned a few things about documentation that I’ll be putting into practice for myself.
- Documentation doesn’t work if it’s based on “what you think users should know” rather than “what users want to know.” And while you can try to force yourself into the mindset of the user, it’s much better to actually involve the user. This needs to happen both at the outset of the documentation creation process, and on an ongoing basis, so you can keep improving your documentation. I have long been dissatisfied with documentation I’ve produced, but I’ve never been galvanized to rethink it. Now I am. Using what I learned at the Book Sprint, my team and I plan to host our own sprint-informed documentation session after the holidays.
- Documentation in a vacuum is not effective: you need to build a community. Here’s another one I already knew already, but the sprint really reinforced and clarified the issue and ideas on how to solve it: users need to engage with the documentation. We need to be able to have conversations with the entire user group. Or it just won’t get used… as I’ve learned the hard way!
- Infrequent, monolithic documentation updates are a real pain, and don’t serve the users. OK, again, I already knew that, but before now I had no solution to the problem. More than once, I’ve been guilty of letting the list of necessary updates sit ignored for way too long. You need the engagement of the community to keep you motivated, and just as importantly, you need the right tools to make frequent updates easy! More about tools later in this post.
Type of book
I think there are a wide variety of types of books that could benefit from the Book Sprint process. Whether or not you come out of the sprint with a book that’s ready to distribute is the biggest question. For a topic in serious need of documentation, often the sprinted book is ready for release, because it fills an immediate need, and a somewhat unpolished book is by far better than no book. This frequently applies to the free software community or any community where there isn’t necessarily the funding to produce documentation or written resources.
For professional publishing-quality books, it’s really no problem. The sprint still gets you way ahead of the game. Feel free to spend more time polishing the work after the sprint before you publish.
The tool that makes it possible
We received expert facilitation throughout the week and without that, a Book Sprint couldn’t exist. Right behind good facilitation, though, is the collaborative authoring and production system called BookType. It was designed expressly for this workflow. It’s a simple-to-use web-based authoring environment, with special sauce. It’s got workflow and version controls. It’s got graphical representations of the data representing the work in progress. It has powerful CSS formatting controls. It outputs print-ready PDF, EPUB, MOBI, and other formats. The best part is, you can easily update the content anytime, and output fresh files. No conversions necessary, no time lag waiting for your EPUB or MOBI. Wow, sounds like the future of publishing is here.