I’ve had a bunch of conversations recently around the role of documentation in hospitality on the internet. My friend and colleague Andrew posted about documentation recently, and of course my love for Buffer requires I point out their approach to documentation – documentation is such a big deal in support communities that we even have a conference dedicated to it.
When it comes to documentation, I am of two minds. Software development, especially code languages and learning code languages, involve a lot of documentation, and a lot of referring to documentation, and so forth. We need to recognize, though, that when we use code to build really awesome things, we are building those things for an audience who is perhaps not as steeped in a documentation-heavy culture.
Working in support for WordPress.com, I am grateful every day for the documentation that we have – for little things that folks can work out for themselves if they have a guide (like, say, a custom menu or static front page), and certainly for big things that are challenging even for me (intricate Theme setups especially).
Lately, though, I have been shifting my thinking on documentation. Part of this comes from doing some deep dives in our Google Analytics account for our docs, finally getting a real bite of how huge our docs base is, and seeing for the first time how much traffic they really get (about 60,000 visitors per day). Recently I’ve started to see documentation as a psychological band-aid, and as a sidestep to improved products. Here’s what I mean:
Docs as a Psychological Band Aid
When a member of our staff recognizes that we have a flow, or a feature, or some other piece that requires additional education, and they invest their time and brainpower in creating documentation for that flow or feature, we can breathe a sigh of relief, right? Now, when a customer asks about that flow or feature, we have a resource for them. That problem is solved. Here you go – read this. We’ve scaled. We can check that box.
The problem here, is that when ever we feel like that box is checked, we calcify our thinking on that issue – we think it’s taken care of. A question about X? Here’s our documentation about X. Especially in a company where staff feels overworked and understaffed (ie, all of them), this becomes the path of least resistance, which then becomes habit. A habit of deferring replies to documentation has two unfortunate psychological consequences: first, it calcifies us in a place where critical thinking no longer takes place. More on this in the next point.
Second, it (inappropriately!) shifts the responsibility from us, as hospitality professionals, onto our customers. It is no longer our job to create an excellent environment where they can accomplish their goals – now it is the customer’s job to read the documents we created for them – time spent in documentation is time spent not accomplishing their goals.
Docs as Sidestepping Product Improvement
Every support document is an admission that a flow or feature doesn’t Just Work. When we create a long series of nested documentation on how to accomplish something is an indication that something is hard to do. A great company makes its customers feel smart, safe, and powerful. Taking someone out of your features, out of your flows, out of the path to their success, to refer to documentation represents a point of friction, an obstacle.
If you want to take the principles of Growth Engineering and apply them to doing hospitality right at your company, take a look at the top search terms in your Support page. Take a look at how people use those documents. Those are break points, those are places where a document is acting as a band aid to a better UX, or a better product (in this, we could learn a lot from modern computer and video games, but that’s a post for a different day).
So What Then?
I don’t hate documentation. I think for a lot of use cases it’s necessary, and it can be done really, really well. I do think that serving our customers to the very best of our ability, however, means reducing our documentation, approaching problems with ownership and a critical mindset – not “Well why don’t they read the guide?” but rather “Why does embedding this require a guide?”
Documentation can be a great tool in the Internet Hospitality Toolbox, but it’s only a temporary stopgap – Docs should be the clamp that holds two boards together while the glue cures, not the permanent solution.
Simon Ouderkirk 
I think you make some good points here, I consider myself to be very pro-documentation, but there were a few parts that stuck out as incomplete, or perhaps, could be thought of in a different way.
At first, your documentation stats surprised me. They are way lower than what we receive on docs.woothemes.com, but looking at that number alone can be deceiving. It’s better to look at why those numbers are low.
In a company that doesn’t take time to focus solely on documentation, you will no doubt have some pages that could use an update or be more clear. Have customers gone to the docs site before trying to find something, couldn’t find it, decided next time it wasn’t worth it to try to search, and instead open a ticket? Have the docs always been easy for customers to find? Do they even know they are there? Is their first thought to search for an answer or to open a ticket?
I’d argue that rather than reducing documentation, perhaps it’s more accurate to think we should be refining it. There will always be a time and place for guiding customers thru setup and ensuring they have the best experience possible, but what about the other 80% that don’t open tickets*? Are they looking and finding what they need? Perhaps they don’t find what they need, leaving the question unanswered and they don’t even thinking about opening a ticket.
Without a focused effort on docs I’m afraid we would never know the answers to these questions. I do not think docs should replace the 1-1 help some customers may need or prefer, but I do think by ignoring them completely you are doing a disservice to the customers that would prefer to find the answer right away themselves.
*I’m basing this on Woo numbers.
Hi Maria!
I hope I didn’t give the impression that I’m ignoring documentation completely! When I wrote this piece I was actually thinking about documentation a great deal!
I think the real thesis of the post is that documentation far too often serves the company creating it, rather than the customers reading it. I see documentation in a lot of products, especially large, do-many-things products, that looks like technical debt exported from the development team to the customers. There’s lots of reasons that this can happen – deadlines, ambitious PMs, whatever – but at the end of the day, any time a product requires a document to be used by its intended customer, that’s an acknowledgement that the product doesn’t Just Work.
I think the best products require the fewest docs – if a product requires sprawling documentation to make sense of, there’s a problem there.
So, I guess all that to say, it’s not really the quality or the findability of the documentation that I’m concerned with here, right? If I have the choice of two pieces of software, X and Y, and with X I can solve my problem just by looking at it and intuiting the interface, and to solve my problem with Y, I have to read a document on a support site, X is inherently a superior product, all other things considered.
It’s not the quality of docs or the doc environment I’m thinking about here, it’s rather the necessity of documentation at all. In this way it’s more an argument about product development, and the way that technical debt handed off to customers is an inhospitable move. Does that make sense?