1. Tony Zeoli

    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.


    • Justin Tadlock

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

    @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. Cavalary

    … 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. Gary Taylor

    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.

    developer.wordpress.org tries to be like http://www.php.net/manual, 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. Joe

    I take away from this excellent article some insights with general applicability. Listen to the people whom you are trying to help. Fix the underlying problem.


  6. Tony Zeoli

    @stefanos Thanks, but I don’t need to be educated on “what Justin just said.” I can read, thank you.

    My larger point is that well-written, updated, and thorough documentation is tied to your brand’s overall image.


  7. Gaurav Tiwari

    I have been a user of WPExplorer’s Total WP Theme and I know how important a well documented theme can be if you are using it to develop for your clients.


  8. Ian Bowden

    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.


  9. Michael K Pate

    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.


  10. Bianca

    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.


  11. Marian

    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.


Comments are closed.

%d bloggers like this: