This is a really nice overview of online Help and it’s really nice to see it on A List Apart!
But I think I’ve found your controversy ;-) (http://twitter.com/mullican/statuses/21489532083). In the last paragraph of the introduction, you say: “No one wants to create it or maintain it. When it does exist, it’s frequently hard to find, poorly written, and not terribly helpful.”
I know several hundred people who would argue with this, me among them. (And there are probably many thousand who I don’t know who wouldn’t agree with it, either.) Our professions include technical communicator, technical writer, online Help developer, online Help author, and more. We want to create that content. We like maintaining it. And we take pride in providing Help and user assistance that is easy to use, well written, and high quality.
(Disclaimer: I own HAT-Matrix.com and TechCommToolbox.com, where you can find a list of tools under Authoring.)
@CharJTF that statement was definitely hyperbolic, but I do think effective help is far more the exception than the rule in our industry as a whole. Kudos to those who do care about it—we need more of you.
Well done article with good recent examples of successful Help applications on the Web.
Long-time Help authors like myself are familiar with these concepts, but unfortunately, like usability testing, our budgets have been decimated, jobs shipped to India, etc. and so although we know better, we’re told to do more with less. Developers at small firms don’t know how to embed Help and don’t want us writers messing with “their” code or possibly interfering with their launch dates. So app Help remains in an HTML or PDF file and simply linked up during the setup build. They also just want “all the commands documented” and don’t really care if it’s organized properly by task and troubleshooting issue. They still want screen grabs for some crazy reason, though…which takes yet more time for what I feel is very little utility (online; it is helpful in print).
It is nice to see how Twitter and some of the newer companies seem go “get it” and go out of their way to think through the “real” user experience. Perhaps we first-generation Help authors will live long enough yet to actually implement the ideas we’ve had all along!
Copy & paste the code below to embed this comment.
CharJTF
@mullican, Thanks! Kudos are always appreciated (personally and for the profession itself).
Think of Help authoring on a bell curve. There’s both good and bad, with the bulk falling in the center of the bell. Then picture that bell curve running across all industries and professions, and (to me at least) it makes sense why good Help is more the exception than the rule. It’s really easy to see why more people experience poorly-written Help.
Technical writing itself is now recognized as a profession by the US Department of Labor Bureau of Labor Statistics in the Occupational Outlook Handbook (http://www.bls.gov/oco/ocos319.htm) and the STC is working on a certification program (http://notebook.stc.org/a-monumental-day-dawns-for-technical-communicators-certification/). Not all tech writers are Help authors, but quite a few are. These two changes alone will help improve both the quality of the output and the pay because they make tech writing a more viable profession.
PS I once complained about T-Mobile’s documentation for the Shadow because a sample screen shot included the “TM” in a field ;-)
Copy & paste the code below to embed this comment.
SDtechcomm
Thank you for this post! Your depth into the intricate UX mechanizations and their potential for building the right, per case help doc is extremely…well, helpful!
As to your mention of the importance of practicing good curation, that couldn’t be a hotter topic right now. Forbes recently ran a HAT software solution that headlines curation and is making pretty big waves in the help authoring community. It is well worth a read for entrepreneurs, those entrenched in their business and technical communicators alike:
Interesting article, and as a technical writer, these are many of the things we try and tackle as part of our remit.
With more companies looking to ‘social media’ to help solve customer issues, it’s interesting that the very websites they are creating might not be all that ‘helpful’ themselves.
The overlap between the various industries at play here is something I’d love to see more of - IA, web design, content management, application design, technical writing – as we can all learn from each other to make that customer experience even better.
Absolutely spot on with your closing remark about raving fans. As a user of Github, I’m constantly delighted by their inline help and help pages. One of the things that makes Github so great is the fact that, although it’s a fairly complicated system, they make it so easy.
This is a great article, and as such deserves one significant correction; “With modal dialogs, you can present longer or more complex content without taking a user out of the current workflow.” Eh hem. While it’s true more content can be contained, because of the captive audience a modal dialog demands, in terms of flow interruption, a modal dialog is specifically for interrupting the flow of a human-computer interaction. I just thought it should be clarified.
@uxdesign-com, I think that would depend on how you define “workflow.” A modal dialog essentially freezes the state of the application or page while presenting its content. in most implementations, that page or application remains visible behind the modal window even if it’s not actionable. So yes, it creates an interruption in the sense that the user can’t complete the task without closing the dialog—but the sense of context is still strong cognitively, so I think it’s valid to consider a modal interaction as part of the overall workflow.
Great read. I whole-heartedy agree with the section on “Questions and Answers”. The additional benefit of structuring your help this way is that it becomes much easier for your support agents to use the help in a support situation. A customer asks, “How do I export a document?” The agent just points them to the help page titled “How do I export a document?”
We follow a method we call “Plan Not to Plan”:http://www.bluemangolearning.com/blog/2009/02/plan-to-not-plan. It is a very simple methodology that has worked well for us and our customers. We basically create out help content based on actual questions our customers have.
Another way to improve help is to include lots of pictures. For procedural type help this will dramatically decrease your reliance on your technical writing skills as the pictures will do most of the work.
Disclaimer: I develop a product, “ScreenSteps”:http://bluemangolearning.com/screensteps, that is designed to create image-based help files. So I might be a little biased :).
Glad to come across a topic aimed straight at the heart of one of my dreaded enemies…the help and support files! Don’t get me wrong, I don’t mind creating them for my client’s sites, I just procrastinate to no end when it comes to implementing them on my own.
For what it’s worth – while I have a meager Help directory that allows clients to view slideshows. I finally broke down and created a “support” form. Currently in the process of creating a Client Portal that will allow them to not only request new services, but also review all documentation related to their account and yes, another, more in-depth, dreaded support request form.
22 Reader Comments
Back to the ArticleCharJTF
This is a really nice overview of online Help and it’s really nice to see it on A List Apart!
But I think I’ve found your controversy ;-) (http://twitter.com/mullican/statuses/21489532083). In the last paragraph of the introduction, you say: “No one wants to create it or maintain it. When it does exist, it’s frequently hard to find, poorly written, and not terribly helpful.”
I know several hundred people who would argue with this, me among them. (And there are probably many thousand who I don’t know who wouldn’t agree with it, either.) Our professions include technical communicator, technical writer, online Help developer, online Help author, and more. We want to create that content. We like maintaining it. And we take pride in providing Help and user assistance that is easy to use, well written, and high quality.
(Disclaimer: I own HAT-Matrix.com and TechCommToolbox.com, where you can find a list of tools under Authoring.)
Lyle Mullican
@CharJTF that statement was definitely hyperbolic, but I do think effective help is far more the exception than the rule in our industry as a whole. Kudos to those who do care about it—we need more of you.
ajanczy
Well done article with good recent examples of successful Help applications on the Web.
Long-time Help authors like myself are familiar with these concepts, but unfortunately, like usability testing, our budgets have been decimated, jobs shipped to India, etc. and so although we know better, we’re told to do more with less. Developers at small firms don’t know how to embed Help and don’t want us writers messing with “their” code or possibly interfering with their launch dates. So app Help remains in an HTML or PDF file and simply linked up during the setup build. They also just want “all the commands documented” and don’t really care if it’s organized properly by task and troubleshooting issue. They still want screen grabs for some crazy reason, though…which takes yet more time for what I feel is very little utility (online; it is helpful in print).
It is nice to see how Twitter and some of the newer companies seem go “get it” and go out of their way to think through the “real” user experience. Perhaps we first-generation Help authors will live long enough yet to actually implement the ideas we’ve had all along!
CharJTF
@mullican, Thanks! Kudos are always appreciated (personally and for the profession itself).
Think of Help authoring on a bell curve. There’s both good and bad, with the bulk falling in the center of the bell. Then picture that bell curve running across all industries and professions, and (to me at least) it makes sense why good Help is more the exception than the rule. It’s really easy to see why more people experience poorly-written Help.
Technical writing itself is now recognized as a profession by the US Department of Labor Bureau of Labor Statistics in the Occupational Outlook Handbook (http://www.bls.gov/oco/ocos319.htm) and the STC is working on a certification program (http://notebook.stc.org/a-monumental-day-dawns-for-technical-communicators-certification/). Not all tech writers are Help authors, but quite a few are. These two changes alone will help improve both the quality of the output and the pay because they make tech writing a more viable profession.
PS I once complained about T-Mobile’s documentation for the Shadow because a sample screen shot included the “TM” in a field ;-)
SDtechcomm
Thank you for this post! Your depth into the intricate UX mechanizations and their potential for building the right, per case help doc is extremely…well, helpful!
As to your mention of the importance of practicing good curation, that couldn’t be a hotter topic right now. Forbes recently ran a HAT software solution that headlines curation and is making pretty big waves in the help authoring community. It is well worth a read for entrepreneurs, those entrenched in their business and technical communicators alike:
http://www.forbes.com/2010/08/07/customer-service-fulkerson-technology-documentation.html
SDtechcomm
meant to say Forbes recently ran “an article about a HAT software solution”…
Gordon McLean
Interesting article, and as a technical writer, these are many of the things we try and tackle as part of our remit.
With more companies looking to ‘social media’ to help solve customer issues, it’s interesting that the very websites they are creating might not be all that ‘helpful’ themselves.
The overlap between the various industries at play here is something I’d love to see more of - IA, web design, content management, application design, technical writing – as we can all learn from each other to make that customer experience even better.
skilldrick
Absolutely spot on with your closing remark about raving fans. As a user of Github, I’m constantly delighted by their inline help and help pages. One of the things that makes Github so great is the fact that, although it’s a fairly complicated system, they make it so easy.
uxdesign-com
This is a great article, and as such deserves one significant correction; “With modal dialogs, you can present longer or more complex content without taking a user out of the current workflow.” Eh hem. While it’s true more content can be contained, because of the captive audience a modal dialog demands, in terms of flow interruption, a modal dialog is specifically for interrupting the flow of a human-computer interaction. I just thought it should be clarified.
Lyle Mullican
@uxdesign-com, I think that would depend on how you define “workflow.” A modal dialog essentially freezes the state of the application or page while presenting its content. in most implementations, that page or application remains visible behind the modal window even if it’s not actionable. So yes, it creates an interruption in the sense that the user can’t complete the task without closing the dialog—but the sense of context is still strong cognitively, so I think it’s valid to consider a modal interaction as part of the overall workflow.
gdevore
Great read. I whole-heartedy agree with the section on “Questions and Answers”. The additional benefit of structuring your help this way is that it becomes much easier for your support agents to use the help in a support situation. A customer asks, “How do I export a document?” The agent just points them to the help page titled “How do I export a document?”
We follow a method we call “Plan Not to Plan”:http://www.bluemangolearning.com/blog/2009/02/plan-to-not-plan. It is a very simple methodology that has worked well for us and our customers. We basically create out help content based on actual questions our customers have.
Another way to improve help is to include lots of pictures. For procedural type help this will dramatically decrease your reliance on your technical writing skills as the pictures will do most of the work.
Disclaimer: I develop a product, “ScreenSteps”:http://bluemangolearning.com/screensteps, that is designed to create image-based help files. So I might be a little biased :).
chrismauck
Glad to come across a topic aimed straight at the heart of one of my dreaded enemies…the help and support files! Don’t get me wrong, I don’t mind creating them for my client’s sites, I just procrastinate to no end when it comes to implementing them on my own.
For what it’s worth – while I have a meager Help directory that allows clients to view slideshows. I finally broke down and created a “support” form. Currently in the process of creating a Client Portal that will allow them to not only request new services, but also review all documentation related to their account and yes, another, more in-depth, dreaded support request form.
Thanks again for the read. Very informative.