* The Business of Software

A former community discussing the business of software, from the smallest shareware operation to Microsoft. A part of Joel on Software.

We're closed, folks!


» Business of Software FAQ
» The Business of Software Conference (held every fall, usually in Boston)
» Forum guidelines (Please read before posting!)


Andy Brice
Successful Software

Doug Nebeker ("Doug")

Jonathan Matthews
Creator of DeepTrawl, CloudTrawl, and LeapDoc

Nicholas Hebb
BreezeTree Software

Bob Walsh
host, Startup Success Podcast author of The Web Startup Success Guide and Micro-ISV: From Vision To Reality

Patrick McKenzie
Bingo Card Creator

"Teach, Don't Tell" - article on user documentation

This is a nice article on writing user documentation in order to teach the user the domain and how the software is relevant to it, rather than cataloguing the names of buttons and such.

It's explained comprehensively with good examples.


Not much user documentation is written the way he advocates these days - but it should be.
Scott Send private email
Tuesday, September 03, 2013
It's also a good idea to make software easier to use :) Eg. self-explaining UI, Wizards, tooltips etc.
Kuzmitskiy Dmitry Send private email
Wednesday, September 04, 2013
Guy could take advice himself while he was writing that long @ss article. Everything he wrote there could have been put on one page or two...
Blocky Send private email
Wednesday, September 04, 2013
Blocky, +1.

I got about halfway down and it reminded me too much of the Miss Anne Elk's theory of brontosauruses.  (http://www.youtube.com/watch?v=U6zWjUhfj-M)
Racky Send private email
Wednesday, September 04, 2013
Incomplete documentation is worthless.  If there is a possibility I won't find what I'm looking for, I won't bother looking at all.  And documentation is not what the developer creates to keep track of a project, it is what the user uses to figure out how to accomplish something with your software.  Two very different types of documents.

So there is no such thing as documentation that is too long, but there is documentation that is poorly organized and difficult to impossible to quickly locate the information the user needs.  If your software is exactly the same as what the user is familiar with, there is no need for documentation (and the user probably won't read it), and there is no need for the user to purchase your software, either, because it doesn't do anything that the user can't already get from other software. 

Software either works or it doesn't, there is no market for software that works 90% of the time, when the competition only works 80% of the time.  So there is no point in developing software that only does what its competitors do.
Howard Ness Send private email
Wednesday, September 04, 2013
You should check out the world of software that is hard or almost impossible to switch between. Kind of like a monopoly in a sense. It's nice here!
GregT Send private email
Wednesday, September 04, 2013
I don't agree with your assertions about documentation or about completeness of software (your 90% example).
Scorpio Send private email
Wednesday, September 04, 2013
Scorpio, I'm not talking about completeness in terms of performing every function correctly, I'm talking about  correctly performing specific tasks all of the time, or none of the time.  Users very quickly quit using functions that don't work all of the time.  If software doesn't perform a task the way the user expects it to, most users will check once to see if they are doing something wrong.  Only a few users will check twice, and those that do check twice will most likely re-check their first avenue of support. 

Incomplete documentation means that the user has no alternative but to find another avenue of support, which involves more effort on the user's part and has a lower likelihood of success.  You might argue that users will turn to peer documentation first, but if a software developer is counting on other users to provide more complete documentation than what was provided by the developer, the developer is going to have a lot of disgruntled users.  Even peer documentation has to have a reference to go to in edge cases.  Unless the developer can provide one to one support 24/7 with no waiting time, the developer needs to provide written documentation.

Of course, if every task performed by your software is similar enough to other software already used by your customers, that they can figure out how to use it without any support without fail, then why not just keep using the software they are familiar with?  To compete, your software has to a) perform tasks in a better way (better in terms of how the user interacts with it, not better performance that is invisible to the user), b) perform additional tasks that competitors can't, or c) correctly perform tasks that competitors don't always perform correctly.

For a) and b), your users need some kind of support in order to learn how to perform tasks with your software.  Randomly clicking on buttons doesn't teach your users anything.  For c), it's a little more complicated, but in my experience with customers of sophisticated products, the primary reason a product doesn't perform as expected is because the customer's expectations don't align with what the product can do, and the second most likely reason is because the customer doesn't fully understand how to make the product perform the way it is expected to. 

In all of these situations, the solution is better support, and better documentation is the least expensive way to provide better support.
Howard Ness Send private email
Wednesday, September 04, 2013
Scott, thanks for the really good link.
I followed one of the author's references and found myself at http://jacobian.org/writing/great-documentation/, which is an even better article I think.
DanDan Send private email
Wednesday, September 04, 2013
Howard, I wouldn't want anyone to assume that I was somehow against documentation, or quality software for that matter. It is just that I think things have moved on.

For B2C, as you say, users are very fickle, but the proportion who would consult documentation, however good, when they had an issue is vanishingly small. More likely, they will ask their peers or just give up and move to the next solution.

For B2B, users often have "solutions" foisted upon them, but even then, when they get an issue they will likely turn to their peers and if enough people have the same issues either the software will be abandoned or "someone in IT" will "look into it".

At no point does the intrepid user dive into the wonderful documentation. If you're lucky, someone might google it and stumble upon your documentation page online, but that is a whole different kettle of fish, which has nothing to do with quality.

Of course, this is all IMHO, YMMV, etc.
Scorpio Send private email
Thursday, September 05, 2013
"just give up and move to the next solution"
I was with you until "and."  Especially in a work setting.  If an employee can't accomplish the assigned task with software s/he is familiar with, the next solution isn't different software, it is a different behaviour.  If you can't compose expressions in Excel, you use a calculator and manually enter computed results in the spreadsheet, you find a reason to have the task assigned to someone else or you complete a different task to achieve the same result (to avoid having to change employers). 

This situation doesn't make the employee happy, either, because changing behaviour is very expensive to the employee in terms of effort and stress, and doesn't improve their status at work one bit. If (and this is a BIG if) the software has useful and understandable documentation readily available, the employee will use it.  The reason s/he doesn't use it, is because s/he has been burnt so many times in the past wasting time and effort to learn how to use software that doesn't have that quality of documentation.

"turn to their peers...'someone in IT' will 'look into it'"
Actually, the same thing applies here as well in both personal and work settings.  The level of computer literacy within peer groups is almost always confined to a very narrow range.  And knowing how to use hardware or completing a Google search isn't the issue.  The issue is accomplishing something specific to that peer group.  If you have a problem, your peers don't know how to fix it, either.  It's getting the necessary results that count, not using software more skillfully.  Again, software either works, or it doesn't.

Having "someone in IT look into" anything is also very expensive, far more expensive that the value of the task the user is trying to successfully complete.  In my milieu of manufacturing, "IT" is a) external contractors or b) a cost centre in another division in another country that is under siege from cost-cutting accountants.  If you need to prepare a budget for your manager for Friday, and you are really to hurl your keyboard 43 floors down to the pavement, "IT" isn't going to save you. 

The Canadian division of the manufacturer I work for has about 1500 employees outside of our plants, less than 10 of whom can use VLOOKUP or HLOOKUP functions (and less than 8 after you deduct the two pricing analysts who report to me).  Finance has a long time employee who used to be able to write SQL queries, but hasn't done so in about 10 years, and I'm the only one who knows how to compile a program.  My employer had an IT department with staff that could write code if they had to, many, many years ago, but the Y2K gold rush made it impossible to keep them, and the bean counters jumped at the chance to contract away all of their functions.  We still have a global VP of Information Systems with a marble and walnut office on the Eastern Seaboard, but she's a figurehead with a skeleton staff of assistants.

We pay trainers to come in and teach middle managers how to put together a PowerPoint presentation, and any employee that wants to take an extracurricular course in order to learn how to use software that "might" be useful in their job, will be reimbursed for the cost.  Swearing at monitors is the single largest productivity killer in our workplaces.  It's not that we haven't tried getting better documentation, whether it's on-site training or audio-visual materials, but what is out there is so low quality, submitting employees to it is another productivity killer.  None of it teaches people how to do their jobs, it tries to teach them the menu structure of the program.

I'm almost finished, so let me state that the real problem is that only really simplistic tasks can be reliably performed by 99% of users using the software that is available today.  Yup, if all they need to do is look at images on a web page or read 140 character text messages,  they don't need documentation and the current state of the art software will accomplish those tasks every time.  For everything else, in our own little domains, we would be better off with pen and paper.  But the papered office could only run with a full complement of clerical staff, and we eliminated those positions even early than the in house IT department.
Howard Ness Send private email
Thursday, September 05, 2013
A few years ago we bought a rather expensive piece of software which had absolutely abysmal and useless documentation that had been written by a technical writer who obviously knew nothing about the problem domain and was just bullshitting his way through the documentation by listing names of menu and dialog items but without giving any context or real life examples. Quite a bit of it read like sales copy, talking about the "innovative feature" set and "timesaving operations" over and over.

I complained a lot to the company. Finally they produced a set of instructional DVDs and told me that buying the tutorial DVDs was the solution to the documentation problem - but the DVDs cost $995!

I gave in and bought the DVDs. Take a second and see if you can guess if they were normal DVDs that play in a DVD player.

Nope. They were data discs which contained an encrypted video player which would only play the video data if the original DVD was in the DVD drive AND there was an internet connection to validate the license to watch the DVD while you were watching it!

Not only that but the whole thing was badly written and pinned the CPU so I had to upgrade the computer just to play the DVD at all.

At that point it turned out that it ran full screen mode only so that you could not follow along with the tutorial or take notes of any kind. It also was incredibly slow and constantly crashed, taking the whole OS down with it.

I eventually managed to view the whole thing, though it took weeks to get it all straightened out for about 8-10 hrs of video. The video as you might have guessed was a super enthusiastic guy repeating words over and over like "easy", "simple" and straightforward". The tutorial spend the first 80% or so covering things like how to save files or copy and paste. When it got past all the basics there was zero useful content.

Here's the lesson. A company that makes some bad documentation makes ALL their documentation bad. There's no such thing as a company that makes bad documentation but has good documentation available for an additional fee.
Scott Send private email
Thursday, September 05, 2013
Howard, I thought I made my distinction between B2C and B2B pretty clear, but it seems like you misunderstood what I was saying.

Speaking personally, I have spent the past thirty years designing and building complex software for big business clients in numerous industries, including insurance, investment banking, telecoms, retail, utilities and the military.

However complex these systems were, none of them had any end user documentation, not a single one. Sometimes there was a training programme to get people up to speed, but mostly the software was designed with the users involved, so it reflected how they wanted it to work and they and their peers just "got it" straight away.

Not a single person in thirty years has asked me for user documentation. I'm not just saying that for effect, I'm just being 100% honest.

Being brutally honest, in some of those environments (investment banking or military especially), referring a user to the documentation when they had an issue would get you fired. The software was expected to work and be obvious enough that anyone familiar with the job could be productive immediately.

There I have to take issue with something Scott said in the original post: "...writing user documentation in order to teach the user the domain..." This is not how the real world works, in my experience. Nobody gets hired without domain knowledge, then gets told to learn about it by reading some software documentation. That's just ludicrous and insanely inefficient.

Of course, I am talking about my own personal experience, and that of close peers, but I find it hard to believe that out of the dozens of clients I worked for it is just a coincidence that they didn't want or need user documentation.

As always, IMHO, YMMV, etc.
Scorpio Send private email
Friday, September 06, 2013
Maybe I'm beating a dead horse, but "military especially" doesn't square with my experience.  Perhaps the prime contractor is producing all the documentation, or your military clients are producing their own.  If we sell flashlights to the KL (Dutch army), not only do we have to supply full assembly instructions, but we also have to explain in detail which components are interchangeable with other flashlights used by other NATO countries, and describe the physical properties of each component so if Hans McGyver needs to fix his flashlight in the field, he knows what type of nail and what length of baling wire to use.

I would imagine financial trading software is mission critical like billing software is to us, so if your software is making money disappear, the first step is to contact 24/7 support and scream obscenities at the poor schmuck who is next in the queue.  Which is fine, what we pay for support is less than what it costs our shareholders if we quit collecting money for a couple of days.  In the S&M (sales & marketing) division however,  our problem isn't pushing the right button to mail out invoices, it's finding the right information to correct the human mistakes and misunderstandings that threaten to stop our customers from sending us money.    Not only is it expensive to have every employee calling support every day, but if it is more complex than a password reset, it has to be escalated. 

Useful and understandable documentation  on every desktop computer would not only reduce our IT support bills, but our employees would be much happier and more productive.  The problem is that useful, understandable and readily available documentation is rarer than unicorns, and we don't allow our employees to go hunt unicorns on company time either.

This isn't just for MS Office users, the same thing happens with expense reimbursement or order entry, and the time and wages wasted on getting minor problems fixed adds up.  We've already got Oracle contractors providing us with the most simplistic web apps money can buy, but if terms of sale are altered to accommodate a special situation,  Larry Ellison doesn't have a single employee who knows what a proper contract looks like,  and I don't have the budget to spend $50,000 per incident to get the web app tweaked. 

The most common solution is to make a lot of noise and activity until the customer either gives in and does business with us in a way that the fields on our web app will be properly filled out, or drops us.  Eventually, we will get them back, because our competitors are operating under different, but similar, software related handicaps.  So, I guess we also need more suitable software along with better documentation, but I'll save that for my next 10,000 word essay.
Howard Ness Send private email
Friday, September 06, 2013
Very nice post. I think the hypothesis that users don't want documentation and won't read it doesn't jive with the tech book section at places like barnes and noble. You find at most a few shelves of professional books about engineering topics that are actually useful and of interest to me. Then there is several hundred feet of shelf space devoted to books on how to use Word, Excel, Photoshop and Windows 8. For a given popular program like Photoshop there might be 100 linear feet of new books released per quarter.

Someone is buying those books. Someone who is not finding what they need in the provided documentation.

If you sell something that has fewer customers than Photoshop though you don't have the luxury of just letting freelance tech writers in the aftermarket handle it.
Scott Send private email
Friday, September 06, 2013
Howard, I'm just recounting my experience across dozens of projects for numerous clients over 30+ years. I'm not advocating either way.

My military example is something I've mentioned here before. That is, a hardware and software monitoring system attached to the main steam line of a Royal Navy nuclear submarine. There was literally no documentation. No user manual, no specification, no technical documents at all. The captain of the "boat", along with one of his engineering officers came to visit the office as it was being built and I gave them a demo. They looked at each other, nodded and signed the project off. They weren't interested in documentation, which makes sense, as where would they store it on the "boat"?

As an aside, I was actually a scruffy student, working part-time for beer money without security clearance, but I had to buy a suit and scrub up for that day, so I could pretend to be a senior employee of the contractor. I don't know what they'd have done if I quit, as nothing was written down and I was the only one who knew anything about how it all worked. I guess they could have reverse-engineered it, or started again, but that would have been expensive.

In general, I suspect that documentation is at best an afterthought. I'm not saying that is how it should be, but it seems to be how it is. Maybe it is different outside the UK, where I did most of my work, although usually it was for massive multi-nationals, so if documentation was common, I'd assume it made it over here, via company policy, if nothing else.
Scorpio Send private email
Saturday, September 07, 2013
Forgot to mention, with the submarine example, I asked the Captain if he wanted to be able to print out anything at all from the management console (which was actually a Toshiba laptop that I'd taken apart and re-tasked). He said he wasn't interested in that and if it ever gave any error message, he'd take a photo of the screen and send it to me, via ship-to-shore comms.
Scorpio Send private email
Saturday, September 07, 2013
Scott, I think your book store analogy doesn't really apply to my realm of business applications.

A lot of those books are about teaching non-professionals how to use tools like Photoshop. Also, software doesn't come with printed documentation nowadays, so if you want something to read on the train, the aftermarket is a good option.

You could make an argument that time (and hence expenses) should be spent on "proper" documentation, whatever that means, but it isn't an efficient use of capital. I suspect it is better to put that additional effort into making the software behave in a way that the users expects, then you don't need documentation.

As always, IMHO, YMMV, etc.
Scorpio Send private email
Saturday, September 07, 2013

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz