Don’t forget your stakeholders and their practices as you improve and change documentation. – That was the humbling lesson I learned (once again) as I presented our revamped documentation to non-tech comm colleagues.
Reporting on progress
The company I work for currently moves its documentation towards more structured writing and topic-based authoring. We’ve already rolled out redefined processes and several topic-based user manuals, so it was an opportunity to present to non-tech comm colleagues what we’d done already, why and how we did it, and what else was in store. I talked about topic-based authoring and how it’s chunked, task-oriented, reusable, and independent of delivery format. Then I talked about the benefits and challenges:
- For users, topic-based help can be updated more frequently, it is easier and faster to use online, though it breaks the narrative flow
- For everyone working on our module, it means easier contributions
- For the company, it allows to leverage* content after one-time migration efforts
* I know “leverage” is not a verb, but there were managers present who love the word… 🙂
I thought I was pretty clever for presenting how cool the new documentation was not primarily for writers, but for users, my colleagues and the company as a whole. And it did go over well on the whole. But there was…
The thing about trains
The most contentious issue turned out to be an unexpected use of the documentation: Current user manuals sometimes contain flowing prose walk-throughs of sample setups with many screenshots. When they are written well, they are nice to read. And allegedly users like to print out the PDF files and read them on the commuter train.
The problem of prose
There are several problems with the narrative manuals for users:
- They are hard to use and search in, unless you want to know exactly the one thing they are describing.
- Any sample setup is bound to miss what they need by a little or even a lot, because our product is highly configurable (you can even customize field names in windows).
There are problems for writers as well:
- The prose is really hard to update when functions or processes change because the narrative flow may require small or large changes in several places.
- The screenshots take longer to update and localize than mere text.
I gave these reasons, invited colleagues to check out the manuals done in the new fashion and cited survey findings that most of our users consult the documentation when they have a specific problem, though very few actually read manuals end-to-end.
But the ultimate lesson for me was that I could focus on our mission all I want, I also need to address the change with my stakeholders not only in rational terms, but also in terms of their habits and expectations.
Your turn
Do you think the customer is always right, even if he asks for documentation that is harder to maintain and harder to use in most cases? How can you promote change among stakeholders which you are sure will benefit everyone in the long run? Please leave a comment.
Filed under: change management, localization, managing, single sourcing, structured writing, trends, usability, users |
Kai's Tech Writing Blog 
You have some useful arguments about the problems with prose. Thanks for sharing your thoughts. I know I’ll need to draw on them!
Thanks, Karen – I actually thought of you as I wrote this in light of your upcoming TCUK 11 presentation “Content strategy year 1: a tale from the trenches”. I guess our experiences may be very similar… 🙂
Great article! I think topic-based documentation is a hard sell. It’s easier for writers, overall, but it’s my experience that our audience likes a story (when they bother to read our work). When I learned how to develop online help about 20 years ago, a topic-based approach made sense. But now I’m not so sure. People want context and relevance.
Thanks, gottafang! I agree, my audience likes a story as well. However, I’ve found that by combining topic-based authoring with task orientation, I can include context as well as relevance, mainly in concept topics, but even in the beginning of procedural topics.
A few methods I use to promote change:
Know what you’re talking about and show them you know. Tell them whys and hows. Yes, I shamelessly use terms that I know management isn’t familiar with. It sets me up as an authority. Trusting change is easier when you trust the person running it.
Tell them how they’re getting what they want. This only works when you KNOW what management wants, of course. Explain how your solution, though different than their vision, meets the requirements better.
And when other methods fail, distract them. Show them flashy, shiny, new stuff. Use distraction to change what they want. Show them how your independent-of-delivery-format content can be tailored for a mobile phone — wouldn’t that be great for the train!
I think this makes me sound pretty manipulative, so I’ll stop now.
Thanks, Kathy, for sharing your tactics! I find earning stakeholders’ trust usually goes farthest and is best to implement a solution, esp. if it differs from their expectations or visions.
I’ve also had good experiences with competence and authority, not least because it engenders trust.
Personally, I shy away from distraction: I don’t especially care for it when I’m on the receiving end. And I tend to seek out managers with good sh*t-detecting skills – who lose my respect when they let me get away with it.
We’ve been this route, and you’re right for all the reasons you mention. However, a compelling argument in favor of narrative tutorials is that they can tie together what are sometimes disparate features into a story that users can follow and might not necessarily be able to put together themselves from a series of task-based topics. Many years ago when we were using task-based topics almost exclusively, someone at the VP level cracked open our doc set and pronounced — not incorrectly — that there was no obvious way to get from point A to point B in the docs. It was an eye-opener.
FWIW, our “end to end scenarios”, as the current handle has it, are extremely popular with users — per their comments. Which is to say, users say that they really like these tutorials and pageviews are often initially very strong. But it’s not clear whether the tutorials would hold up as documentation that users would revisit if they need to refresh their memory or find a specific task that’s buried in the tutorial. Hence your insightful point that sometimes it’s a matter of keeping the customer happy on their terms.
I do want to note that it can seem to make the most sense to design docs around what’s easiest or cheapest for us, but which might not necessarily be what users (or here, stakeholders) want (or say they want). While maintenance certainly is an important consideration for designing a doc approach, we want to be careful not to let it trump usability or some other customer requirement. (From one perspective, this can be an example of premature optimization. Consider also the probable lifetime of your docs and whether the issues you’re concerned with (like maintainability) will even be issues before the doc in question is replaced.)
PS re: “leverage”. If it walks like a verb and it talk like a verb, it’s a verb. If there are people who don’t like it as a verb, that’s a different discussion, but we should not confuse the facts of grammar with the opinions of usage. 🙂
Thanks, Mike, for your thoughtful comments!
We’ve come across the same discussions as you have. The best we could come up with so far has been to offer maps for “end-to-end scenarios” in the parent glue topics of manuals, either as a sequences of topics or even as trees with branches, depending on requirements and preconditions. So it’s one of the main functions of the parent topic for a manual or a manual section to explain how to read and apply the string of individual procedures. This seems a worthwhile compromise, because it allows us to keep our topics intact and reusable at the small cost of creating such glue topics primarily for the manuals.
Your point about the popularity of these end-to-end scenarios highlights that they are one of the most useful purposes of documentation – but ultimately one among many. In terms of my “Top 10 things that users want to do in a help system“, they’d be number 5 “Get advice”, though users also want to find individual answers – and then find them again.
And the compromise between the documentation’s usefulness and the efficiency in creating and maintaining it of course remains a conundrum. But I think it’s good and necessary, because it challenges us to frame our work in business terms.