Notice: This is a discussion thread for comments about the SitePoint article, Help! User Documentation that Works.
Is writing help pages and user documentation a high priority for you when building a site? What are your tips for writing good help?
It SHOULD BE!!!
Frankly, there is not enough room on this forum for the volume of tips that would be necessary in order to write “good” help. There is so much to take into account and so many details to be considered, it would literally take me months to write it all down, and I could fill volumes!
This same functionality can be handled by using plain old CSS so that you don’t have to worry about those site visitors who have JavaScript disabled.
Please re-read my statement.
The statement above is not necessarily true. Even a “handful of authors, writing together and all at once” does not guarantee that the documentation will be any better. It may have a consistent look and feel, and may even have the same writing style, but the steps can still be incorrect, misleading, out of order or left open to interpretation. I cannot tell you how many times I have read through user documentation written by well-educated authors and developers “working synchronously,” that still left the end user (site visitor) bewildered.
Why don’t you just make it easy on yourself AND on your web site visitors and hire a good Technical Writer to do your documentation. Technical writers are trained experts in creating all types of documentation some which include visuals, audio and video. Why not leave it to the experts who can guarantee that your site visitors WILL understand and that the calls/emails to your help desk will be greatly minimized.
In reply to:
“In the old phase of our online insurance sites, there was originally little question marks next to some form questions which, when clicked (IF and only IF you had Javascript) would make a popup containing additional information about that question (like passenger insurance, something which may differ between insurers or many people have never heard of such a thing in any case).”
This same functionality can be handled by using plain old CSS so that you don’t have to worry about those site visitors who have JavaScript disabled.
I didn’t think you were trying to hog credit at all, I’m surprised my post came off like that!
I just found the article lacked concision. In light of the definition of “works”, I can’t even fairly say that anymore, can I? You grew a beautiful, juicy apple. Better than 80% of apples I see. I’m just an orange guy.
Hey guys,
Thanks for these great, thoughtful comments. I really appreciate them 
I definitely agree that the nature of the user audience dictates the level at which you pitch help content, what it contains, and the way you present it. User testing is of course necessary to determine how well your work has hit the mark, and where more work is needed.
But I also think that covering as many of the audience-appropriate bases as possible in the way you present help content is crucial; to make elements like Pachey’s in-help references to interface elements as usable as possible, images with appropriate ALT text would be essential, for example. But the fact that there are users out there who, for whatever reason can’t perceive colour or spatial location doesn’t mean we can’t use these references. In my books, it just means that they should be augmented with alternative content formats so that all audiences are addressed.
Also, DED and BLZ, I’m sorry if it seemed like the article didn’t give enough credit to the original authors of the help content, which was, as I mentioned, crucial to the process of identifying content gaps and what was already working (and therefore getting a handle on what the audience was familiar and comfortable with, and what they didn’t understand), as well as to developing an appropriate voice and approach for the help content redevelopment.
To be completely honest, I’m a bit bemused by the comment that you felt I was taking the credit for developing the ideas of usability and interface design These tenets are integral to the successful execution of information design and communication, and particularly here at SitePoint, I imagined they would be well and truly on the radar, and seen as integral rather than a separate point that needed to be addressed independently. They’re just part of the job, right? I wanted to cover them as part the discussion (because they’re crucial, and because so many designers of help content seem to overlook them) but I didn’t think I needed to point out that they weren’t my invention 
Finally, I have a question. The argument I’m positing in this article is that user documentation that works is user documentation that speaks directly to the audience, showing them how to achieve their goals on the site, helping them to grasp unfamiliar concepts, and creating a sense of rapport between them and the brand.
For me, “works” doesn’t just mean “lets user achieve goals” or “reduces support queue”. It also means “supports business objectives” and, very importantly, “creates positive emotional response in user”. I presented the case of Flippa as an example, because the solution any of us might choose for help content, in terms of formats, IA, nomenclature, presentation and structure, will vary in every single case.
I’m curious as to what you believe user documentation that works would achieve in addition to these goals.
Thanks again for the discussion!
Georgina
The Unknown Audience can ALWAYS sneak in, even when writing for an intranet for some company. Even if you don’t happen to have any colour-blind seniors, someone will get a crappy old monitor from the grandkids. I have a monitor at work that seems to make all yellow (and white too) look green-tinted.
Hm, true, though I’d still say at the least, the “voice” of the documentation would be consistent. But yes, it doesn’t mean it’s usable by the audience (in open source you still often see docs written by developers in developer terms… non-nerd users really can’t read it). How-to user documentation would ideally always be written by those with knowledge of usability and usability testing.
Good points - I should have mentioned I knew who I was writing the manual for and they didn’t have such issues. I hope I remember such things when writing for an unknown audience!
@Stommes
Yes that would make a better documentation. But, my point was more that what was in the article has been tested and documented while the article didn’t seem to give credit to those who came before.
Another point to your statement, however, is that even in the condition you state, a small group of writers working together all at once, won’t necessarily make for a useful documentation. The writers have to be aware of user needs, cognitive psychology and other learning factors.
For instance, a given person’s self-efficacy is usually lowered when learning new material from an unfamiliar domain. As an example, where a math expert can easily learn new math, a non-math expert with the same cognitive abilities might have difficulties learning the new math simply because they don’t trust their own ability to understand the material.
So even when the documentation is clearly written from the stand point of those working on a project, you won’t know if it’s useful without outside input.
By the way, I didn’t mean to imply there was something wrong with points being made in the article. And, you made some good follow up points in your previous comment as well.
I thought most of the article blamed the bad text on the fact that multiple developers over a period of time didn’t create a seemless, coherent set of documentation— it was all over the place in several styles.
A handful of authors, writing together and all at once, whether they were usability experts themselves or not, would have made better docs either way.
I was a little disappointed by your article. While your points are useful and backed up by research, you seem to blame the originators to your points for writing bad help files. In the second paragraph you say bad help documentation probably comes from usability experts writing the help file. Then you mention several guidelines that are all well established in the usability field i.e HCI, and UX design. It comes off as if you believe you and Flippa established these guides yourselves when in fact they are over a decade old. I believe you should be more honest about your writing and if you are unaware that these are established practices your should have done research before mis-aligning blame. Otherwise it’s a good article with valid points.
DED
Honestly, it didn’t speak to me that much.
Perhaps I was just unclear on what was meant by “works” in the title. Seemed to flip flop between the author meaning that it reduced support requests and meaning it’s a great tool to reinforce branding. Lacked the concision that one usually associates with documentation in general.
It was pretty readable. I found it dry myself, but then again I think that has a lot to do with my interest level.
On the plus side, it did highlight very well the holistic approach needed on new concept sites. It clearly illustrated that might take more doing than we’d first think and that it’s incredibly important.
As somewhat who writes user guides, training guides, etc… for a living the first thing I tell a client is that I am not including screenshots in the documents for the simple reason that sg707 mentioned above, they make the documentation impossible to maintain.
On a more general note, the bane of documentation is poor design. No matter how well you document a poor GUI design/naming system you’re just going to be putting lipstick on a pig. Bringing in UI people and the such at the beginning is critical to a project’s acceptance rate with users. But with that said I’ve seen some absolutely horrible designs come from usability people as well.
Eg telling them a link was at the top left, or saying the ‘Insert image’ icon was a yellow square.
This is good for those who can tell a yellow square from a white one (some people cannot), and for those who can see a “top left”. Also mentioning before/after (regarding source order) would also cover anyone who was blind or not using a graphical browser or something.
Good user documentation is really important for us, mainly because it minimises the number of times we get a call or email saying ‘How do I do…?’
The most recent manual I wrote was for a group of old people, to help them use their CMS. It was an interesting experience because they have far fewer assumptions about how things work than younger folk.
I included descriptions of where to find things (something I don’t see a lot of in help documentation). Eg telling them a link was at the top left, or saying the ‘Insert image’ icon was a yellow square. It saved them (and me) a lot of time and headaches!
In a real world w/ a great System Engineer. He’ll be sure to add “User Training Document Testing”. Unfortunately… these people are hard to find. Also, maintaining the user guide is very crucial too. For example, if the author takes screen capture of the shot that included “headers” and “footers” all over the document then… expect high maintainance. Each time a developer changes either headers or footers then the documentation is no longer in sync. I remember having a great suggestion for the site but due to… high maintainance of user docs… it was a no go.
At our company, no. Which is a shame.
In the old phase of our online insurance sites, there was originally little question marks next to some form questions which, when clicked (IF and only IF you had Javascript) would make a popup containing additional information about that question (like passenger insurance, something which may differ between insurers or many people have never heard of such a thing in any case).
When I came along, my first thought was to remove the Javascript and use CSS. This brought more access, also to search engines if they bothered looking at forms they could reach, but this is still silly. While people do want to dive into forms that look easy (they start off asking stuff you know like your name and address), it’s much less user-friendly to use popups, tooltips or even links to whole new pages to explain terms, prices and restrictions mid-form. Ideally, the user would get informed of these things (mostly) before going further than getting a quote.
Currently the pages are still following that model. Initially we needed to use target attributes for any form labels that went to new pages (they were too long to be tooltips and explained changes in motoring laws) because those without browser caching would come back to an empty form. Now it’s with sessions, so we’ve seen through our stats that more people continue through the forms than previously.
Really, what would solve these problems, and was just briefly mentioned in the article, is user testing. Ideally users who are not familiar with your content. According to Steve Krug, they DON’T have to necessarily fit your targetted user group… most of the biggest problems on your page can be found by just anyone who knows how to point and click.
Another thing I remember Krug mentioning, and this also had really brief mention in the article, was that it’s really not a good idea to assume your users know your jargon terms, even if the group you are targetting is some profession who supposedly uses those terms. So, auction terms, you might think you’re getting those people familiar with eBay or something, but Flippa didn’t. It got lots of new people. Krug mentioned a site using some strange real estate term which the developers were sure all agents were familiar with. In user testing, many agents asked what the hell that word meant.
For developers such as myself who don’t really have the freedom to make good changes to sites for users, there are still a lot of little things you can do.
One thing I was able to insist on is, any time the user has attempted to submit a form and it came back with errors for whatever reason, the very bottom of the form had a little line stating “If you’re having issues, you can also contact a human being at (tel num) or (email)”. People use it! They catch form bugs for us (yeah, they shouldn’t be the ones doing that, but we don’t have user testing here : (
Absolutely nothing is more frustrating than getting stuck in some software loop with no opportunity to contact a person. After finally signing up for PayPal, I found that I cannot contact them. They say “use the contact link on the bottom of the page”, but clicking it sends you to a “help” page, where it’s explained that it’s not available in my language (whether it’s English or Dutch). I’m pretty sure they DO have an English version, but I cannot seem to access it. In any case, I was expecting contact information, not a help page. Two different things. So, developers who can’t make large changes in their layouts or setups can still make sure stuff gets named correctly, and that links actually work. I go through our sites when they go online and click every single link. There’s always a bad one in there due to typos. Frustration for the user! Easily avoided.