Got Issues?

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!

Content Issue Pie

Content Issue Pie

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).

Mangled image

Mangled image

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.

Issues Created Monthly

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:

  1. Standardization: custom fields, boilerplate language
  2. Automation: QaQ, automated email
  3. Elbow Grease: Monthly issues export & follow up
  4. 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.

Component Pie

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!

30 Day Summary to Beat

0 to Book in 3 Days?

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.

GSoC Doc Camp Books – Evergreen, FontForge, Etoys as paper and electronic books (kindle, android, iPad).

Google Summer of Code Doc Camp Books. Evergreen, FontForge, and Etoys as paper and electronic books (Kindle, Android, iPad).

My takeaways

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 takeaways

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.

  1. 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.
  2. 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!
  3. 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.

Check out my daily posts, or for more information, see

The Alchemist and the EPUB

Publishers sometimes ask me, “What [ tool | filter | app ] should I use to save my [ Word | layout ] files to EPUB format?” And I have to be the bearer of disappointing news: it’s not that simple. EPUBs that are produced using the sorts of tools that offer a Save As… EPUB option are files that may validate (with a bit of luck), but no one will want to look at those ebooks, and you certainly wouldn’t want to offer them for sale.

Alchemical apparatus engraving from Basil Valentine his triumphant chariot of antimony, 1678,

Let’s back up for a minute. Why are we in this situation of wanting a somewhat mystical solution to producing ebook files? I say it’s because of two key publishing workflow needs that make the process more complicated than it might seem to non-publishers.

  1. Publishers need an authoring/editing system that is ubiquitous and easy to use, to give them the flexibility of working with many different authors and editors working on a variety of platforms. The collaborative nature of manuscript development requires review passes with visible, user-identifiable changes and comments, and the ability to accept or reject changes one-by-one. Most publishers use Microsoft Word to fill this role. Some publishers use Word in conjunction with file sharing applications that offer version control and collaboration features, but most simply email docs back and forth and rely on a human project manager to keep things straight.
  2. Publishers need sophisticated layout and paging controls (such as those provided in Adobe InDesign) to produce beautifully designed print books. Even for the driest of technical books, good design is essential for readability. Final edits and corrections are made in the layout files, which means that the layout files—and ultimately the PDF that gets sent to the printer—become the definitive work.

These two requirements have locked publishers into a workflow that has them building the print book first, and then creating the ebook from the print files. Creating an ebook from layout files can be partially automated to the degree that layout files are consistently structured (a tall order), but some amount of manual work is generally involved. It’s a time-consuming process frequently taking a minimum of one week, sometimes longer. And it’s not free. While the cost isn’t necessarily prohibitive for a single book, it adds up when applied to a publisher’s entire catalog. And finally, many publishers have learned the hard way that file conversions introduce the potential for errors. So they’ve had to build quality controls and checks into their process, costing more money and time.

The more intrepid publishers have taken the plunge into XML workflows, some (notably, O’Reilly) very successfully. But most publishers have shied away from costly XML systems because it just hasn’t been practical to find one that fully meets the two requirements outlined above, or at least without breaking the bank.

It almost goes without saying that any new solution must fill both of the requirements I keep talking about, and of course also output printer-ready PDF, bookmarked “uPDF”, EPUB, and MOBI. The good news for the would-be alchemists is that we seem to be on the brink of a solution.

Let’s tackle requirement #1: An authoring/editing tool that is ubiquitous yet offers the sophisticated collaboration and review controls. Well, what is more ubiquitous than a web browser? At Books In Browsers 2012, we saw demos of applications that hint at delivering this requirement through the browser: Adam Witwer of O’Reilly demoed Atlas, and Adam Hyde of and FLOSS Manuals demoed Booktype, which offers a SaaS model for customization. Maureen Evans and Blaine Cook demoed, which offers browser-based, traditional-looking (only more beautiful) collaborative editing features that were a delight to behold.

Moving on to requirement #2: Controls for beautiful design. Adam Witwer showed us complex page layouts produced in Atlas, and my colleagues at Safari Books Online have been experimenting with pushing the boundaries of what Atlas and CSS can do, with exciting and encouraging results.

So… sure, the tools may be slightly immature at this moment, but they are under active development. It’s clear to me that we (and after a lifetime in publishing, I identify myself as a member of the publishing community) need to begin making the move to modern publishing. Why not get to know a developer working in this field and collaborate to build the exact tools you need? Why continue looking for the philosophers’ stone to turn one thing into another completely different thing, when you could produce your gold right from the start? The new world of publishing tools tantalize us with their shiny potential: to save money and save time, without sacrificing quality either at the press or in the e-reader.