The Best Documentation Is No Documentation

Hear me out before telling me how wrong I am.

Over the past couple of weeks, I have read a few different articles on writing good user documentation from a software developer’s perspective. It is an area I was always told I excelled at by people who read the docs I wrote through the years. However, by the time I stepped away from my WordPress business of over a decade, I had almost completely stopped writing user documentation. Few users seemed to have noticed or questioned why there were no step-by-step explanations of certain features.

Like many WordPress plugin and theme developers, I am a firm believer in having documentation on hand. As someone who has been fiddling with code since 2003, documentation has been my best friend. I have written at least a few hundred tutorials or pages of docs throughout my career. I have published two development books and was a technical editor on a third. I am fairly certain I have created a plugin or two with more inline documentation than actual code.

However, I also ran support for end-users for over a decade. The one thing I learned with any surety is that many users simply do not read the documentation. Even if they were reading it, they should not have needed to most of the time.

Despite iterating, redesigning, and trying my hand at everything to lead users to documentation before running to the support forum with every question, repeat questions never failed to land in the support queue every day.

It took me years — far more than it should have — to realize that the solution was not in the documentation and the problem was not in the user’s ability to read it. The problem was the product. If users were asking repeat questions, it meant there was something wrong with the user experience. Eventually, I shifted my focus. Instead of writing more docs, I focused on addressing the problems that continued to crop up in the software.

The activity that I had failed at was listening.

One of the best skills a developer can obtain is the ability to listen and then translate what users are saying into better code, user interfaces, and user experiences.

In my younger years — and I suspect many developers were the same when starting — I felt like I knew the answer to every question and was always right. I was highly skilled, and I knew it. For a young, 20-something developer, that tends to mean trouble. It means that you believe the problem is not with the things you have built. No, the problem was that the user was doing something wrong. These are the types of developers who say, “RTFM,” and point a user to an overly technical document that does not solve their problems.

Some lessons are learned the hard way, but learn them we must to build better products.

I promise if you do this one activity — listen, really listen — to users, you will spend far less time explaining how something works. The question you need to ask yourself is why a piece of documentation needs to exist in the first place. If it takes 500 words to explain a feature, there is a good chance the feature does not make for an ideal user experience.

When building products, we should always strive to build them so that there is no need for documentation. Or, at least build them so that reading the manual is a last resort for addressing problems.

For practical purposes, as a fulltime developer in the past, I kept a simple text file with a list of repeat questions. This could be a more elaborate setup for a team, such as creating GitHub issues. My text file worked fine because I was a one-person show. I would make it a habit to routinely go through the list and ask how I could improve each point. Some items were never scratched off the list. However, more often than not, I learned important lessons about building for end-users first. I could see the things that made sense in my head but were confusing to others.

The biggest improvements were not in finding solutions to existing problems but in recognizing problems within new products that I was building based on past experience.

Over time, most of my documentation became geared toward developers. These were primarily tutorials on using APIs, hooks, and other developer-related features — things that were not exposed through a plugin’s UI. I was writing far less for end-users because I was updating projects based on their feedback and questions. Yes, I absolutely failed from time to time, but I was getting better at being someone who listened to problems and made changes based on what users were telling me in their own way.

When I say that the best documentation is no documentation, I do not mean that you should skip it altogether. I want you to ask the question about why the documentation needs to exist. Are there things you can do to make the user experience easier? Are you actively tracking support questions and addressing those in the product itself?

In development, we often talk about writing “self-documenting code.” This is a way of saying to write code in a way that you should not have to explain it to another developer via inline documentation. For example, the wp_insert_post() function in WordPress tells you that its purpose is to insert a post. The goal of any software should also be to create self-documenting interfaces and other elements that a user interacts with. Users should be able to automatically understand the purpose of a button, text field, or checkbox without consulting the docs.

The next time you sit down to write a new user-oriented piece of documentation, make sure that you are not using it as a crutch to prop up a poor user experience.


12 responses to “The Best Documentation Is No Documentation”

  1. I am not a developer, I am a VP of Product. My role for my Digital Strategy Works clients and now for myself as a product owner of a WordPress plugin (Radio Station) is to ensure that the information architecture and user experience ensure we have mapped successful outcomes to user stories without the individual having to read any documentation or click on a tooltip to get more info about a feature or process.

    If we’re not creating the user experience that gets the user from A to B and they have to go and read the docs, then that’s a fail in the sense that we’re not completely thinking through how we can take the best approach and create a more usable product.

    That being said, I completely agree with your thinking here in the sense that docs should really only be a fallback of last resort. But, I will say that having good documentation builds brand identity and brand equity. If you have a complete set of user docs that you keep updated, then you’re going to generate positive feelings about your brand. So, while you may spend a lot of time thinking that the hours spend developing your docs is a waste of time, it’s not in the sense that if you spend the time, what becomes visible to your customers is your commitment to the plugin or theme you’ve created.

    I can’t tell you how many times I’ve read docs by foreign plugin developers which failed to explain a feature or are outdated. That creates a negative impression of the brand and the developer. It says, if you can’t keep up, then why should I invest in you and your plugin?

    So, that’s an important consideration that I think you left out of your post. What docs do for brand reputation. Because your reputation is important and if you fail to provide updated and complete docs, then you look amateur.

    Damned if you do, damned if you don’t. LOL.

    • I definitely agree that having docs is essential for building and maintaining a quality brand. All product makers should strive to write solid docs. It’s an important aspect of the business. Mostly, I wanted to focus on devs who use docs as a justification for not building a better product. Docs should be there. The goal is for them to be unnecessary, which will happen only in a perfect world, but we should continue striving for that perfection.

  2. @Toni, Justin basically said:

    Write self-explanatory code
    Avoid bloated codebase
    Document only the areas that need documentation, so even your future self will need reminding of what it actually does.
    By listening to your users helps you write cleaner codebase, it pleases them as well for doing so, and you safe valuable time.
    Keep the technical part(s) to those who really want to get their hands dirty with API and the likes.

    In other words, a TLDR; of a pseudo-TLDR; is this: apply the UNIX philosophy – Do one thing and do it well!

  3. … and this is how everything became dumbed down, simplified, “streamlined”, with features being removed, control taken away from users…
    A good question about repeat questions is who are they coming from. Are advanced, knowledgeable users (not necessarily experienced with the program itself, but with computer use and tinkering in general) getting confused? If so, then yes, there may well be something wrong with the problem. If not, well, adding PBCAK to the RTFM.

  4. Way back, before we even had “the web”, I used to teach an evening class on word-processing. My notes and examples all related to what people could use the software for – real-world examples, not what the software was technically capable of.

    Then I changed jobs and started teaching and writing user guides for Microsoft Office. Again, it was all about showing how the software could do things to help the user.

    Then I moved into public relations, and my releases and similar all took into account what the passenger/customer wanted to get out of things; which was not necessarily what the bosses wanted to say. My work would be customised for each audience.

    In my experience it’s not about documentation, but explanation. tries to be like, but doesn’t have the wealth of user-generated real-world examples that the latter has. In this case, no documentation is better as there are people out there (yourself included) who do a better job of explaining how those functions can be used.

  5. Wow! Is this article ever timely as I have spent the past two weeks in “strained discussions” with a SaaS developer from whom I’ve bought a product who refuses to provide any form of documentation. The discussions I refer to are the many back-and-forth emails we’ve each been sending; me with another question, him with another answer.

    The software does what it’s supposed to do – and fortunately a lot more – and it’s in the exploration and required experimentation of those added features and functions that I find myself getting very frustrated. Since acquiring this product a few weeks ago I have spent literally a half dozen hours trying to figure out such things. Compounding the frustration is that many aspects of the software require some time to pass until the effect of a switch or selection can be understood. For example, the SaaS product potentially generates a weekly report but I must wait an entire week after configuration to actually see the report. No example of it is provided because, as I’ve stated, there literally is no documentation!

    Would I have bought such a thing had I known beforehand that I’d be spending hours experimenting and trying to figure out this somewhat complex proudct? Probably not. I understand software developers not wanting to release full documentation to just anyone interested in their software. Such things can become the blueprint for a competitor making a knock-off. Should I be asking if such a thing is available beforehand?!

    Personally, I love to browse through the docs of most all of the software products I purchase because it gives me the heads-up on things the software can do that I didn’t know about. They often also give me the heads-up on the implications of turning Switch A on that aren’t always apparent.

    In the end, I think most software developers that don’t even provide basic, high-level documentation are effectively stating to me, ‘It would take me X hours to write that documentation and I’d rather you spend X hours trying to figure it out.’ In other words, ‘My time is worth more than your time.’ How arrogant.

  6. I remember once many years ago trying to figure out how to do something at my Mother’s elementary school – I would help them out with their computers from time to time. I found the answer – some written instructions in my own handwriting that I didn’t remember writing.

    Not documenting something is only a good idea if you can trust yourself to remember the answer.

  7. This is a nice, thought provocative article.

    I also read the comments and agree with most of Tony’s comment. “Damned if you do, damned if you don’t. From what I understand, you simply cannot get it right for everyone. However you can try to come close by starting with research. Depending on the market you’re in and the product involved; research involves resources and money. And these aren’t always available.

    I think the necessity of documentation depends on some variables. In the end documentation needs to serve the user to reach their specific goal with the product they are using (whether it be software, a car, a toaster or ….).

    There are many different type of users, with different learning techniques (some read docs, others fiddle about), different skill level(including self-overestimation) , different amount of patience(deadlines) and different personality traits(tempered). And of course with different expectations of the product they are about to use or set up.

    And there are many type of products. Simple products that solve a single “problem” and complexer products that let you do more things. And there is Word of Mouth: They told be “product x” will do this, I read that “product y” would solve that…

    So I think user research including testers helps you to build a better product and good documentation (or a unboxing, installation video) compliments the product. The happy experience adds to the brand image.

  8. I surely agree with your point of view. Every feature should be built to be self-explanatory, that would be a great user experience. Both the developer and the user will save a lot of time not needing to write (dev) or go through (user) a huge documentation.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: