Better Products Through Documentation

One of my goals a decade ago was to create more usable products. One of the ways I figured out how to refine my aesthetic for this was to use documentation (help files or manuals) as a guide post. When I write documentation I focus on consistency and on explainability. If something is easy to explain to the intended audience and it fits a continuity across the product then usually the product is solidly-designed.

As the decade has past I don’t need to write the documentation as much to spot these issues. Now, as I design new components or entire products, I can see the documentation in my head. In fact, I often use the question “How do you explain that to a customer?” while designing or reviewing development work.

For instance, with powerOne version 3 we had a situation where we were trying to decide on a format for a new function call for graphing. For scatter plots it is written one way, for bar graphs another. Well, that is too confusing. (And we are talking about the most technical of our customers here, by the way, as only a small percentage actually write their own templates.) So we simplified the function call so that they don’t have to think so hard about the parameters. In other words, we decided it was better to ask the user to submit a piece of information we would ignore (because we know the answer based on the data) then ask them to do it two different ways.

I correlate this problem with the dreaded IF statement. IF I have this then I do it one way but IF I have this then I do it another. I hate these. IF statements require the customer to remember too much about the product.

I’m sure when Dan Bricklin invented the spreadsheet he didn’t have much choice but to introduce the notation we have all become familiar with in spreadsheets. IF you are entering text then just enter it but IF you are entering a formula then start it with = but IF your text starts with an equals or a math symbol then… Yeah. The reality is that that notation worked at a time when computers were only really used by experts and everything was hard. The last half dozen years are introducing an era when everyone uses a computer and these “non-experts” aren’t going to take the time to learn fancy notations, to remember the IF statements.

Of course the ultimate goal is to completely eliminate the IF statements and completely eliminate the documentation. To make something amazingly powerful that needs almost zero explanation is the ultimate goal. I may never reach it but it is my goal none-the-less.

2 thoughts on “Better Products Through Documentation

  1. There does seem to be a lot of errors in the update, especially when coming to errors.

    Of course, the lack a written manual doesn’t help either.

    BTW, how will you conver between BC/AD and AUC (ab urbe condita) without an if-statement. Remember that 1 AD = 753 AUC and that 1 BC = 752 AUC. Our calendar simply hasn’t got any year 0.

    • Please email us at and tell us what you are finding regarding errors. We obviously want to fix any problems.

      The manuals there. I am getting everything updated on the site this morning.

      As for if statements, I wasn’t talking about in code. I was talking about in explanation to a customer. If statements are always necessary. The goal should be to eliminate as many as possible.

Comments are closed.