Image courtesy of Stuart Miles / FreeDigitalPhotos.net
Once upon a time (sometime in the 80’s) everyone in the tech business was a novice. Novice tech writers wrote for novice users about novice products created by novice developers employed by novice entrepreneurs (most of whom, apparently, had recently dropped out of Harvard).
There were no conventions about how any of this stuff was supposed to work. No one even knew what the business model was for software, let alone what the standard conventions should be for how anything should work in software or in hardware. As the popular saying of the time went, if it isn’t documented, it isn’t a feature.
If it wasn’t written down, there was virtually no way to figure out how anything worked. There was no one to ask because everything was new and everyone was a novice. Tech comm at the time rightly focused on novices. There was no one else to write for.
But times have changed. Tech is a mature industry with an abundance of experienced users using products developed by experienced developers working for experienced managers and executives. The business model for software is well understood, and there are ample conventions for how almost everything works. The world has moved on. Tech comm hasn’t. Much of it is still obsessed with novices. This has to stop or it will put us out of business. What do I mean when I say it will put us out of business? Very simply, documentation is a commercial product. It rarely stands alone (that is a separate business altogether) so it is generally sold as a component of a commercial product. As is the case with any component, it adds cost to the product and potentially affects the time it takes to get the product to market (that is, its opportunity cost). Like any component, it has to justify its cost in revenue terms. That is, it must show that it increases margins, increases share, or decreases costs by more than it cost to build and ship it.
Documentation focusing on novices would only fulfill those requirements if there were a large demand for information for novices — that is, if most buyers were willing to pay more for a product, or to buy more of a product, if it came with lots of information for novices. Is there a large demand for novice information today? There certainly was in 1989 or 1993, when we were all still novices. Have things changed since then? Yes, for a number of reasons:
- Electronics and software are a daily part of our lives today. We have been using them for 30 years now. Even if a new product is a little bit different from other products we have used, it is not nearly as different as the new tech of the 80s and 90s was. The experience gap for new functionality is much smaller.
- We are much better at interface design. 30 years have winnowed out the design ideas that don’t work. Stuff it just easier to use than it used to be.
- We have the power to run sophisticated interfaces. Early electronics did not have the power to run fancy interfaces, to provide infinite levels of undo or to warn about any destructive actions before executing them. Interfaces used to be cryptic and dangerous because they ran on limited hardware. Now they are clear and safe because we have the computing power to make them clear and safe.
- We are all familiar with the fundamental interface conventions shared by all products of a certain class. Standardization makes knowledge transferable — we don’t have to learn the common stuff over and over.
- We are not all novices anymore. While a few people in any family or organization may be novices, most people are experienced and can teach the novices.
- We crossed the chasm long ago. The novices of the 80s and 90s were early adopters. Most real novices today are the laggards, and laggards don’t read documentation. (Yes, there are still groundbreaking products being created which need to cross the chasm, they just don’t account for the bulk of contemporary tech products.)
- The Web makes a world of experts available to help novices. Much of the information demand from novices today is handled by online forums and other Web sources.
In aggregate, therefore, we have far fewer novices, and far more help available for the novices we do have. Demand for information aimed at novices is correspondingly lower, and it is therefore much harder to justify the cost of an extensive novice-oriented documentation set.
The result, inevitably, is that companies are cutting back on documentation, or outsourcing or off-shoring its production to reduce costs. Tech comm’s obsession with novices is driving it out of business.
Why then does the obsession continue? For two main reasons, I suspect:
- Tech comm has been justifying itself by an appeal to the needs of the novice user for decades. — The users can’t understand technical language. Engineers can’t write for novices. Novices need documentation or they won’t be able to use the product. — These have been the stock justifications for so long that we turn to them automatically when challenged.
- Writing for novices is easier than writing for experienced people. The first principle of writing is to write what you know, and tech writers have long positioned themselves as the champion of the user. It is easy to step into the shoes of a novice, to see things from the novice’s point of view. To step into the shoes of someone experienced in both the task domain and the tool domain as they tackle complex problems can be much more difficult.
What must we do to end the obsession with novices and keep tech comm from going out of business? The answer is simple to state, though by no means easy to implement: Find out where the real information demand is today. Find out, specifically, what information demand people are willing to pay to have met. And when you have found it, prepare yourself to meet it.
In this regard, it is important to note that there is not nearly as much of this kind of demand in the B2C space as there used to be (though the demand in the hobbyist space should not be overlooked). The bulk of it is likely to be found in the B2B space, especially as our ever-more-networked world means that products have to have interfaces that allow them to work with other products — which means there is a lot of need for documentation of APIs, data formats, and integration methods. There are similar complex information needs in many technical fields, from medicine to aerospace and manufacturing to telecommunications.
We are not without exemplars in this. There are many tech writers out there who have been working for years to meet the sophisticated information demands of experienced users who are using complex tools to perform complex and important tasks. They are deeply steeped in their subject domain, and they recognize the value of contributions from people with specific technical expertise in particular areas. They are the example of what tech comm needs to be in an era of mature technology and experienced users.
I really enjoyed this article, thank you very much!
To a degree, I agree. What I think is important is to identify any use cases that are unique and describe them. Going into the details of an interface that meets accepted usability standards are wasted words. However, if the interface is complex it behooves us to explain that interface in terms of the use case the interface supports.
The reality is that it’s not as much being entranced with novices that’s keeping us from being a true value add but it’s a viewpoint that we document the product and not help develop a product that meets a customer’s workflow that might keep us from growing. We still need to be the consumer’s advocate but we need to start that at the design phase of all sprints.
Actually, Julio, I suspect that this notion of being the consumer’s advocate may be in part responsible for the continued obsession with novices. You can’t be an advocate for the user unless you understand the user’s job, and understand it well. If the writer wants to cast themselves as a user advocate, therefore, they have to create an image of the user that matches their own level of experience. That is fine if the writer actually is skilled and knowledgeable in the task domain, but if not, it means that the user they are going to advocate for will be the novice.
But what behooves us, though, is not to fill the smallest information gap for the greenest novice, but to create merchantable value for the heart of the user community. If the heart of you community is novices, then they will pay for novice information. If the heart of your community is experienced people, they won’t.
Understood, Mark. That’s why I framed my response in terms of workflow. We need to understand the workflow and our information needs to support the workflow. The problem comes when the development team cannot express that workflow themselves. Then, when we interpret the workflow that seems to flow from the interface, there are discrepancies between the design and the use cases. In most cases, the design stays as is and we wind up trying to document around procedural deficiencies which forces us into the “novice” role.
By being involved at the design stage, we can, even as novices, identify things that don’t make sense or affect usability based on experiences across the spectrum of products we’ve documented. That should improve the product the customer receives, decrease the needed information that supports that product but keeps the team, including the “doc folks” as value added to the product.
I’ve seen many examples where assumptions on the user’s level of experience led to bad design decisions that challenged experienced people in a field because the product was too cumbersome to use and that person needed documentation that was missing because the information was developed with the same view of experience and that the interface was “intuitive”. That experience assumption cost sales at best or increased support calls at worst.
Erring on the side of less experience may increase initial cost in product delivery but may be cost effective in the long run as long as you don’t aim at the gross novice. (“Turn on the power by pressing the power switch located…. “) That’s just unneeded words that help nobody.
That’s a valid point about poor workflow design due to a lack of understanding of the end user on the part of the designers, but it doesn’t necessarily mean the optimal interface design is the one that best suits the novice. I think if the tech writer has some UX background, she can prove valuable in helping design the user interface. However, if she has neither UX nor domain expertise, how is she better suited to making design recommendations than the software architect, or the comptroller, or the janitor?
I think web 2.0 and i-devices have given rise to an over-valuation of the novice and their expectations. If your product is targeting a general consumer audience (Facebook, Twitter, etc.) sure it makes sense to make it dead easy. In that space, the product needs to engage and retain, or else the user will go elsewhere for a better experience. But not all products are for that general consumer, and believe it or not, usability doesn’t trump all. If you’re a researcher using nanopore sequencing software to parse genomes, looking for translocations, the task itself may involve some complex manual pattern matching. You might need a fairly sophisticated interface to do this because the task is, by nature, complex. Sure, a generalist tech writer with no background in biology could be helpful in designing the user interface, but ultimately, probably not as helpful as someone who actually works in the domain for a living, especially when it comes to accomplishing the most complex domain tasks. A novice may attempt to over-simplify the interface because they don’t fully understand the task. The result is a tool that’s worse than difficult to use, it’s *impossible* to use for some tasks, because the advanced user cannot access advanced functionality due to a design that actually prevents it. Sounds crazy? It happens.
Ideally, you want to make the largest number of users as productive as possible as quickly as possible. Maybe the most sensible approach to design is to determine which gross skill level (novice, intermediate, expert) has the largest number practitioners and favor that group? I don’t know, but I don’t think automatically defaulting to the newbie is the best approach for every product.
Paul, I think the same thing can happen with documentation. The tech writer, themselves a novice, and writing only for novices, can actually obscure the operation that the experienced user needs to understand.
Julio, that’s a rather convoluted scenario — though alas perhaps not rare. But it does seem to argue for writing for novices because poor product design has negated the experience of users, turning them into novices. I’m not sure that kind of product will have a long run for the docs to be cost effective in.
Anyway, I will make a distinction between documenting a properly designed product for novices and documenting around design caca, and exempt the latter from my present critique.
Hi Mark, I tend to agree with Julio. The problem, in my view, is not obsession with novices, it’s the idea of documentation at all. At least where software is concerned, the need is not for long documents that you read apart from the activity of using it. People need decision support – “do I really need to do this task? Why or why not? What’s the interest?” That might be enough – but if not, they can then get “how to” in context, which is the best way to anchor the principles in memory so the user only has to ask once. This means user assistance needs to be embedded, and included in the interaction design model from the get-go, not appended somewhere in the packaging. Do that and the level will take care of itself.
I agree that an embedded approach can work wonders for answering a lot of common questions. I remember how much I enjoyed my first experiences with Firefox. When compared to IE or Opera at the time, it had such threadbare yet elegant UI and it felt like every time a question came up, they knew I was asking it and surfaced the answer in an unobtrusive manner. Unlike Microsoft, who would constantly bludgeon you with unhelpful dialogs, which you couldn’t disable, because then, you’d have no idea what was going behind the scenes and mostly likely it wouldn’t be what you’d want or expect. Gaaaaah!!!!
Ray, I certainly think there are many areas in which good interface design and embedded help can entirely obviate the need to documentation in some cases — as, indeed, it has already done so in many cases.
There are fields, though, in which this is certainly not the case. In programming, for instance, all attempts at making programming a graphical rather than lexical activity have come to nothing. Programming, OS, and API products need docs, as do many other things.
Certainly, though, I am not suggesting that the obsession with novices is the only problem in tech comm, simply that it is a problem.
You’ve neatly summarized the discussions we’ve been having over on LinkedIn. Perhaps it’s not so much an obsession with novices, but rather, it’s that the writers themselves are novices in both the product and the subject domain, so they often cannot write above that level without extensive guidance.
I remember a LinkedIn post a while back in which a writer quoted a user as saying, “why do technical writers never write about the hard things?” That can’t be an easy thing to hear if you’re a generalist software tech writer, because it means your only value adds are your English skills and your “critical thinking” (valuable no doubt, but tech writers don’t have a monopoly on this).
I don’t believe it’s necessary for every writer to become a SME in their product’s domain, but it makes sense for them to increase their knowledge of it. Taking courses, shadowing end users, getting involved in triaging support tickets or even handling support calls, all things that would help get a deeper understanding of the audience, instead of assuming they’re clueless newbies.
As you say, we should be documenting the hard stuff, the stuff end users can’t figure out on their own. In the past, I’ve half-jokingly proposed replacing online help with a link to a help forum moderated by the tech comm team. If nothing else, at least writers’ time isn’t wasted on content nobody reads; the only things that get documented are things actual users care about.
Paul, I definitely think there are cases in which writers argue for exhaustive documentation for novices because they really are not competent to write for anyone else.
Protesting the needs of novices over those of all other users may seem like a job preservation strategy, but in the end work that creates no value gets eliminated from the production process — if not by managerial acumen, then by Darwinian pressure on less cost-effective manufacturers.
The help forums, of course, are exactly where people are going, and tech writers are too often conspicuous by their absence from them.
Mark, does it ever bother you that your point of view isn’t earning you any friends at the STC? That’s okay. Mine probably isn’t either.
But re. help forum participation, Adobe’s technical writers (at least some of them) monitor their help forums and “livedocs” and they follow up on user comments. And I always talk about Atlassian as being pretty forward-looking in their approach to documentation and writer involvement in the community. Yes, please, more of that.
Today, there’s video, there’s social media, and there’s an audience out there who’s both tech-savvy and short on attention. Writing 400-page guides and throwing them over the wall like we did back in the day won’t cut it any more (even if they’re authored in DITA). Big companies will be able to sustain that outdated model a little longer, but we already see smaller organizations adopting strategies for communicating product knowledge that are more cost-effective and better at meeting end users’ needs. The changes are happening, and the technical communications profession could (and should) be at the vanguard here, but instead, it feels like most of us are just digging trenches and hunkering down to resist them.
I think the problem lies deeper than only tech writers being obsessed with the novices. There’s more in it.
For one there’s the legal part. Products have to be safe to use. For everyone. Even the most stupid idiots. This results in safety instructions beyond imagination (you remember the microwave/dog incident for sure).
Then there’s the product warranty laws. Products must be usable by the customer – right, even the most stupid idiots.
That brings up the third party. Management. Product Managers tend to overreact if (those stupid idiots I mentioned) users call support, when they can’t figure out how to press that only one button on screen. Document quality is measured this way – not by the standards tech comm uses. They tend to react mildly, if a very special use case isn’t described.
This leads down the route of the least resistance. If (seemingly) everybody wants documentation for the brainless, why even bother putting up the effort not to write for novices?
If you look at it – if we would be writing for experts – why should we bother working for the company that sells the product? Shouldn’t we work as free authors then, selling our own books, making a fortune?
As long as legal departments and managers tell us to write for novices, we simply will have to do so. We may add some value for experts, but only if there is time/money left on the project (almost never).
Do I agree with this practice? No, I would love to see documentation to be useful, for novices as well as for experts. But reality shows, that there is no place for the perfect documentation.
I’ve heard this argument being made before, but it has always come from writers, not from product management and not from the legal department. Sure, maybe what you describe applies to some industries, but it’s certainly is not representative of all or even the majority. I would contend the number of writers working under strict legal requirements to write for the “stupid idiots” you describe is relatively small.
At least, speaking for European audience, those “some industries” involve nearly every B2C industry. Product liability is a mayor influence on documentation. I know there are regions in the world, where those influences aren’t as massive (like in most parts of Asia for example).
Also especially machinery construction and medical equipment production has got very strict rules to write documentation for.
In the past you could write for a target group of well educated operation staff, but nowadays as many contract workers operate machinery, the courts tend to neglect this.
Regarding product managers, well I’ll give you an example:
Some years ago, I wrote some operation manuals for bio-ethanol fireplaces. Our first level support received a call from a customer, asking if he could place the fireplace under a wooden stair. They forwarded the call to second level support, which escalated it to the product manager. The product manager then stood on my doorstep, asking if this would be appropriate.
You may imagine, that I couldn’t believe what I heard. Fireplace under wood? Yeah, right, is it April already?
So I answered “No, for sure this ain’t appropriate! Fire is hot, and if you don’t want to burn down your home, you don’t place it under a wooden stair.”
Two days later, the legal counsel of the company showed up, asking me why I did not place a note into the manual, that you shouldn’t use the fireplace under flammable materials and that I should at least insert a comment, that fire is hot.
Ridiculous. I didn’t know who was the most insane guy in this chain. The guy asking the question? The support guys escalating the issue? The product manager? Or the legal counsel?
This is just one out of many examples I experienced myself or heard of from colleagues in other companies.
Yes, like disposable coffee cups that have the words “caution! contents is hot!” 🙂 It’s not unreasonable to include warnings in owner manuals for products where there’s risk of bodily harm — ones that feature open flame, chemical reactions, nuclear fission, motor vehicles, etc. But how many writers (might be a good LinkedIn poll) are actually employed by companies building those kinds of products? Yes, I now know at least one 🙂 I may very well be wrong, but I don’t believe the *majority* of technical writers are documenting those types of products.
The software industry is one of the largest employers of technical writers, and just about every piece of commercial software is accompanied by an end user license agreement that includes clauses to limit manufacturer liability, disclaim warranty of merchantability, etc. Notwithstanding additional rights conferred to the purchaser in some jurisdictions that can void those clauses under certain conditions, software manufacturers are generally not held to the same level of accountability as, say, bio-ethanol fireplace manufacturers.
But many software technical writers are operating under the ill-conceived notion that they must treat their audience like 4-year-olds, including an excruciating level of detail (yet still managing to be incomplete if you ask some readers) as if the consequences of a misstep while operating their product are on par with cutting the green wire instead of the red one while defusing a bomb.
The technical writer has an obligation (if not legal, at least ethical) to ensure the safety of the audience (their health, business assets, finances, etc.). But the actual risks vary depending on the product. For many of us, the products we document present minimal risks, and it doesn’t make sense that we waste the audience’s time with pedantic prose for fear of some imagined legal threat.
Paul, I agree on the business of treating the audience like 4-year olds. While writers always claim to be focused on the user’s needs, it often seems like they are pretty contemptuous of the actual users.
Tech support is full of stories of spectacularly dumb users, and I have more than once heard writers cite these stories as justification for producing reams of agonizingly elementary documentation. But it is not our job to write for the stupidest imaginable user — if for no other reason than stupid people don’t read documentation.
Alex, if you know of a way to make a fortune writing technical books, could you let me in on the secret?
It is a fair point, though, that in some cases we document idiotic things as a defense against being sued by idiots. But that hardly covers the whole of the territory. And I doubt that the person who calls tech support about how to push the only button on the screen is going to read the docs before doing calling. If someone lacks confidence to that degree, they generally want a live person to hold their hand.
And I should point out that I am not saying that we should not write for novices at all. What I am saying is that we should write for each segment of the audience in proportion to their willingness to pay. Ridding ourselves of an obsession with novices does not mean not writing for novices at all; it means considering the needs of all users equally.
Those “xyz in a nutshell” books sell quite well, I heard 😉
But back to the topic. The point I’m trying to make here is, that the tech writer community is often forced into writing stuff they wouldn’t even care to explain normally.
I’m saying the most pressing force are not the stupidest possible users, but the guys that decide how a product ships and the law enforcement.
I would be damn glad, if I wouldn’t have to write trizillon times “Click Next to continue” and I try to avoid these stupid procedures whenever possible, but if I do so I have almost always to explain why I did so to a product manager.
Tech writers have one mayor problem: What we are doing is always judged by people not having the slightest clue about our work.
Another problem is the circumstance, that every product shall be usable by everybody. You won’t find a single responsible person to tell a customer, that he’s better off with not using the product because he’s too stupid/not trained well enough in the general area the product works in.
Those responsible persons just will ask you, the writer of the documentation, to explain it for even a 3 year old.
Alex, you raise a very good point. Product managers, who are often not really interested in documentation, tend to specify “the same as last time” for the docs requirement of every project.
I know of a company, though, where the product managers demanded “the same as last time” year after year until suddenly they fired half the tech writing team and replaced them with engineers because they suddenly found out that “the same as last time” was not working for users.
Producing something of no value because someone who isn’t interested in your product tells you to is not a safe long-term strategy. We need to start educating product managers that the the tech comm world has changed. We need to persuade them to let us create economically valuable documentation before they discover for themselves that we are not.
I have issues with the article for a few reasons:
1. The Tech Comm field did not spring to life suddenly in the 1980s in response to some documentation gap noted by budding software companies… the oldest piece of technical communication I know of is a recipe for beer found by archeologists on a four-thousand-year old Mesopotamian clay tablet.
2. Just because software user guide documentation is experiencing a change in focus does not deny that there will ALWAYS be new technology to introduce new users to.
3. In the 1980s I knew of experts in several technology fields who still needed and used documentation… and many who didn’t. By the 1990s I knew one gentleman who had been in computers his entire career, and was 88 years old. He had been involved with the early naval computers. He was eager to learn Java scripting at the time.
4. There are other kinds of technical communication and documentation than software user support.
Thanks for the comment Faye.
You raise some good points. I’ll address each in turn:
1. I agree completely. Tech comm is very old. But something changed in the 80s, both in who tech comm was writing for and who was doing the writing. The tech boom created an anomaly in which everyone was a novice and all the usual mechanisms of apprenticeship which usually prepare people for a task broke down. It suddenly became all about the novices and a new novice-centered tech comm doctrine was forged. But the anomaly has resolved itself and the normal ratio of novices to experienced people, and the usual mechanisms of apprenticeship are working again. The market has reverted to the norm; tech comm has not.
A cookbook is actually the perfect illustration of this. The vast majority of cookbooks are written for experienced cooks, and most people who learn to cook learn by helping their parents in the kitchen. There is little apparent demand in the market for books on how to boil water.
2. Absolutely. My point is not that we should never write for novices, but that we should not obsess about novices or address their needs and interests exclusively at the expense of the rest of the audience. We should write for the demand, and only a small part of the demand today comes from novices.
3. People in technology do need documentation. There is no “still” about it. Experienced professional technical people need and use documentation all the time. Good documentation is not something you read once and throw away, it is something you use regularly to do your job. Unfortunately, tech comm’s obsession with novices means that the documentation working professionals need is often incomplete, inaccurate, or missing, which puts a significant dent in their productivity.
4. Agreed. And in many of these fields, technical communication remains a technical discipline and never went through the transition that software/electronics tech comm went through. It is important to remember that while the majority of what is said and written about tech comm practice does come out of the software/electronics space, there are other world of tech comm to whom much of what is said and written does not apply.
To eliminate the need for novice instructions, I believe, is to put the onus on an individual who can instruct another in how to begin using the software. I think not of a well-educated individual but one who for the first time is encountering the software, be it a 4 year old pre-school student, an 7 year old first grade student or an third-world adult who has the funds to by his or her first computer. Either a more experienced user or novice instructions will be needed to assist these individuals.
There is another solution to removing the need for novice instructions from the documentation and in doing so make it easier for the user. I speak of wizards that perform basic commands. With wizards, then only intermediate and advanced operations need to be documented. If the user can follow the wizard operations, then also having the wizard commands could be engineered by the user to do the steps manually or adjusted the wizard created commands.
I don’t really think Mark is saying we shouldn’t write for novices. He’s just saying we also need to write for more advanced users. Just because they’re further along doesn’t mean they don’t need assistance.
The problem I see is that, so often, the software technical writer tries to write multiple guides at the same time:
1. PCs for Dummies (because users may not know how to turn on the computer)
2. Windows/Mac/Linux/Solaris for Dummies. (because users may not know how to find the File menu or use cut/paste functionality or mount a volume)
3. Internet for Dummies. (because users may not know what links on web pages look like or that you can interact with them to navigate to other web pages)
Phew! That’s a lot of work already! Do I still have time to talk about my product? Well, I think I’ve done enough to at least help the new users get started…
You cannot hope to teach your users all the prerequisites. It’s fair to draw a line and state that they must have some prior knowledge and experience in certain areas before they attempt to learn to use your product. If you do this, it frees you to focus on your product, which is what the users really need from you. You can refer your users to existing documentation produced elsewhere, which will probably be better than whatever you could write in the time you have.
As for wizards, on one hand, I feel like they’re too often a band-aid solution for a poor initial UI design; if the wizard is just a more intuitive way to perform the same task, why bother keeping the other method? And if the wizard hides more advanced options, how useful is it really? Wouldn’t it be best to just create one good interface instead of two? On the other hand, one size doesn’t always fit all and I think wizards can be useful, especially when they’re designed in such a way that they also serve as a training tool, preparing the user for the “big boy” version of the interface, or when they are not so much wizards, but rather, “quick” style interfaces, allowing the user minimal opportunity for error, defaulting to the most common options, all while gently reminding them at strategic points that some options are still available but must be accessed elsewhere.
Paul, exactly! The opposite of obsession is not abandonment, it is treating all users in proportion to their willingness to pay for the product we are providing. (We are not running a charity; it’s not what they want, it’s what they are willing to pay for.)
On wizards — is it not bordering on the absurd that people create wizards because the UI is too hard to use, and then document them because, apparently, the wizards are too hard to use. What happens if the docs are too hard to use, I wonder.
No, it is not absurd. Sometimes the UI is too hard or would require knowledge of programming to accomplish a task.
Installation wizards compensate for the need of knowing the proper directory hierarchy and register placement.
Oracle Discoverer’s workbook wizard, for example, compensates for having to know Structured Query Language (SQL) and what results can be read by a novice with some SQL knowledge.
For the novice, whose job may not be a programmer, who wants a quick and dirty report to be used for information or exported to another application such as MS Excel, the workbook wizard serves this purpose.
If we follow the Quality Assurance adage that 20% of your issues will take 80% of your time, this is a reduction of calls to the support desk to fix installation issues or having programmers do the work.
If I recall, manufacturing systems implement a form of artificial intelligence to alert the monitors to issues in the process and may offer suggestions on how to rectify these issues. I recall hearing about this in the steel industry on keeping blast furnaces at optimal temperatures back in the 1980s.
It is not dumbing down the user, so much as making the user part of the process and giving insight into black box processes that the user would need to monitor manually through multiple interfaces.
Scott — You make a fair point. I was thinking about the wizards that sit on top of the normal interface, but there are plenty of interfaces where the wizard-like approach of step by step question and answer presentation is the first and only interface. Documenting those interfaces is not so absurd as documenting the interface that was supposed to simplify the previous interface. That said, good wizard design, whether the wizard is the first of second layer of the interface, should be largely self documenting.
What a wizard sometimes can’t do, though, is cover all the decision support information that someone might need in making the decisions about which options to choose in a wizard. This is why, as I wrote last week, decision support is the real docs need. Unfortunately, when tech writers obsessed with novices document wizards, what they often do is focus solely on how to work the wizard itself (which should not need documenting at all) and omit any decision support information.
I would make a distinction, though, between creating an interface at a higher level of abstraction (such as a report writer as a layer over SQL) and catering to novices. The report writer is not created for novices, but for people working at a different level. The people who start off using report writers do not go on to learn SQL, they just get more proficient at using the report writer. If you document the report writer only for novices, you will fail to support the needs of more sophisticated report writer users who want to do more complex tasks with the report writer.
I used to work (briefly) for a company that made sophisticated software for decision makers. The product manager insisted that I write for novices since most of their clients were only technical assistants, drool-proofing everything. I thought he was wrong, but was careful to not assume too much intelligence. It didn’t matter and they let me go, saying one of their testers couldn’t follow my instructions. A year later, that firm laid off the tester, manager and everyone else but the top management. I went through many other successful contracts and now work at a wonderful place making very sophisticated geophysical software for decision makers. We don’t drool-proof our online help. Instead, we offer courses and tutorials for beginning geophysicists and use our help for the more advanced users. We’re rated as leaders in our industry and are doing quite well, so people aren’t shunning us for the lack of drool-proofing. I suggest that Mark is right with respect to the online help and that novices really need guided tutorials instead of manuals, at least for software intended for smart decisions.
David, thanks for the comment. I love the phrase “drool proof” and will be looking for excuses to us it in a sentence real soon. 🙂
“I suggest that Mark is right with respect to the online help and that novices really need guided tutorials instead of manuals, at least for software intended for smart decisions.”
I agree completely. I work with another writer to create documentation for a billing and finance product, and it’s the complex tasks and edge cases that our customers really need help with. For example, it’s very easy to create an accounting period in our system; but the user needs to know why they want to do this, what they need to consider when configuring it, and how it’s going to apply to their billing and payment processes.
Because we’re a small team working with very short release cycles, we start with the easy stuff (because users do ask for it), and then document the more complex topics as product knowledge propagates through the company (meaning that we’re not as dependent on the one overworked PM who can explain how the system works).
Pingback: Why simplicity is more important than functionality in content navigation - Every Page is Page One