"The fact that this is even a point of discussion [is] incredibly depressing."

That was the closing line in an email to the entire company—one sent in objection to a decision I had made two months into my current role at Red Hat. Reading that, along with an avalanche of similarly themed (and some more colorful) emails, the day after returning from vacation, was sobering. The more I read, the more I realized that (in addition to being highly critical of the decision I had made and the way my team had carried it out) the authors of these emails had something else in common: they were right.

The problem: A shifting documentation landscape

When I began my current role at Red Hat, leading the global team that produces all of our product documentation and other customer-facing content, I was excited by our opportunities to change and to try new things in a part of the software world that has been remarkably slow to evolve (despite the intensity of innovation happening all around it). In 2015, a good deal of software documentation is still produced as books, delivered in PDF format, as if designed to be printed. When you get a new software application or tool, do you think, "Before I get started, I should print out the 500 page manual that comes with this?" I didn’t think so.

We provide our content to customers in four formats: as HTML pages in which each section is a separate page, as HTML pages in which the entire book loads in one giant page, as PDF downloads, and as ePub files (for use with e-readers). Looking at downloaded data, we can see how people consume content from our website (the mutli-page HTML format is most popular), and getting feedback from a variety of stakeholders and customers (they tell us they don't want giant books; they just want the information they need, when they need it!), led me to a pretty straightforward conclusion: We shouldn't be producing large books designed to be printed. Instead, we should be creating content that’s more modular and easier to search, allowing readers to zero in on exactly what they’re looking for, rather than assuming they’re going to open a 500-page book and read through a table of contents. Additionally, more modular content allows us to incorporate additional features like user comments and other interactive elements to engage with customers, to gather feedback, and to promote continual improvement.

So, my team and I decided to try it out. For the next major release of Red Hat Enterprise Linux beta, we would not ship the PDF and ePub formats of the content. We also wanted to remove the option to look at an entire book in a single HTML page (we made that decision partly for technical reasons). Instead, we would encourage people to find what they needed via the search engine, provide our docs in the multi-page HTML format, and move toward a more modular based approach in our content development.

Here comes the avalanche

The response of Red Hatters on memo-list was swift and clear:

"That is a crying shame! :-/"

"Removing html-single is a regression rather than an improvement."

"Life is more difficult [with this change]"

As it happens, I was on vacation when the memo-list response broke out, so I couldn't respond. My team did a valiant job defending the decision, engaging with the critics, and trying to explain our strategy. When I returned from vacation, the dialog was still going on. My first reaction was surprise; we had looked at the data, and the percentage of people who used these formats was very small. Why are people so passionate about this?

But the more I read the replies, the more I realized they had some really good points. They presented use cases we hadn't considered. And, they had one very valid criticism: We were putting the cart before the horse. We changed the way we were delivering the books, but we hadn't changed the structure of the content enough, and we hadn't done enough to improve the search functionality and make our strategy feasible.

Release early, release often

While some of the sentiments seemed to assume that I was an idiot with bad intentions (those were hard to read), the vast majority of them assumed the opposite—that my team and I had good intentions and good goals, and that we just hadn't considered all the details. To the outside observer, being "eviscerated" on memo-list feels harsh and scary. While that's true (getting criticized in front of the entire company is never fun), it's also a great part of the decision making process.

I replied to the thread to take accountability for the decision, to say thank you to everyone who provided feedback, and to explain how we would incorporate their feedback and temporarily reverse the change while we worked toward reshaping our content. I was surprised—and grateful—for how many people took the time to respond, this time thanking me for listening to them and owning the decision.

Here’s one detail that may have been lost on some of the critics: while it seemed like we had made this decision in a vacuum, it was actually a kind of controlled experiment. We didn't roll out the change across all products at once; we did it only on one product, and for a beta release at that. Initially, I wanted to see how people would react so that we could continue to iterate.

As we say in open source, "release early, release often."

Because no matter how much due diligence you put into any decision, there will always be something for which you didn't account. Planning for time to receive feedback and iterate on an idea might take a little longer, but ultimately it leads to outcomes that are better for everyone—most importantly, our customers.

And that's the ultimate goal.

Follow the conversation on Twitter #theopenorg