Why users can't find answers in help material

Notes de l'éditeur

1. Where I live and workFamilyInterests: visual communication, screencasting
2. Notice how few people responded about the necessity of the PDF. This is interesting. Makes me wonder about its utility. So much time and effort gets dedicated to producing a PDF that it seems like some of the other tasks and responsibilities get overlooked. Also, not many responses about the language, even though the emotional component of help is kind of a big trend right now.
3. Why the game? Want you to stay engagedI want to learn somethingI don’t pretend to have all or even the best answers
4. This is symptomatic of people who burse framemaker PDFs into online help. Story: Mark Baker calls these frankenbooks. When you decide to burst a framemaker book online by splitting out each h2 as its own topic. When you’ve seen this it’s creepy. You land on a page but it doesn’t make much sense by itself. It relies on some other topic but it’s not clear what the context is.Information that was never intended to be consumed on the web is now forced into this paradigm. And it shows.
5. Much more preferable is the wikipedia style. Let users jump to the section they want. Make information self-contained on the same topic.Page length is one of those impossible discussions. How long should a task be? If you follow a methodology where you have just one little paragraph as a concept on its own page, you’re doing something wrong.Some topics are 1 sentenceWhy long pages:Easier to find info – fewer targets to hitUsers learn other stuff while browsing. This is why supermarkets are put the bread at the back – forcing you to peruse other parts. The TOC becomes easier to browse. Not infinitely massive.Easier for authors to maintain because info is all in one placeArgument for short topics:User enters keywords and goes right to the exact topic (so not reality)Usually user search queries are poorUsers don’t know the right terms to search forUser can’t even articulate the problem with the right terms
6. My preference. Why force users to go all over help material. Esp. if they don’t have the right terms to properly navigate the information! Story: first started using these with flare. Works great b/c you can easily add on information. Greatly simplifies this information. Some objections: can’t see it all at a glance, search results pages don’t automatically expand the right section.You could essentially have all documentation on a single page
7. Story: experience of trying to figure out the rules for how words get parsed on twitter. Reason I couldn’t find them is because I wasn’t looking under tokenization. Also wasn’t searching for chunking. “word boundaries” “filtering rules” “matching filters”Story: putting together antenna. “matching transformer.” refers to it so casually as if everyone knows what a matching transformer is and a rubber boot.“cashtag”I asked SEO guy at CSA conference. He says pick one and be consistent, but do backend synonyms. Also create some paragraphs that explain the two terms.
8. Story: this is how people use help files. Each search informs them of something that makes their next search a bit smarter. Searching and browsing go hand in hand. We should stop thinking of them as separate, independent activities.Story: omnibus. Sacrifices each way. If users see Omnibus on a button, they’ll expect to see Omnibus in the help. If it’s not there, it’s pretty obvious the tech writer objected to the term but was overruled.Glossaries, indexes, table contents – all this can teach you the right words.
9. Example that Leah Guren gave during her talk. You get instructions for answering a call or accessing your contacts, but rarely both.
10. Deke McClellend’s tutorials on Illustrator. Puts tasks in context of each other. This also gives you a great opportunity to test whether your help covers all the bases.
11. Story: creating narrative workflows for decision point. They seemed pretty useful. Not sure why I stopped creating them. Partly it’s because we’re bombarded with task-concept-reference categories of topics. This one doesn’t seem to have a clear place where it fits.
12. How many times have you winced and thought, why even bother, the manual won’t answer my question.Story: come home to find that my wife ordered $40 worth of books that were shipped to the wrong address. No way to fix.
13. Story: current predicament: content geared for both marketers and developers. For marketers, the API and SDK information doesn’t mean a whole lot. For developers, the details of the reward info might be more detail than they want. This is especially problematic with technical information where the audience has varying levels of understanding. Story: asked a plain language expert, Deb. Bosely. Says to choose one audience. I think the collapsible sections can be a great way to solve this.Writing for one audience doesn’t really solve the problem, because I’m not going to create two separate sets of online documentation.And how exactly do you know where one audience’s needs begin and end? I guess this is the classic admin user versus regular user dilemma, except that when you take content online on a web platform, you don’t chunk it out into different websites.However, you can have different articles on the same site. One article may be geared toward marketers, another for devs. Don’t need to mix them on the same page. You can also tag the articles.
14. Story: ramping up on JS SDK. Subscription to Safari. Problem is that it takes a lot of time. One has to be an expert in so many different fields. It’s a lot to ask of people, and really, how much do I learn by reading books on JavaScript? How do I get to that expert level of knowledge that is really needed to write documentation that would be highly useful to developers?
15. Problems with HATs:Story of putting Flare online versus the Mediawiki site.IframesConstantly changing linksGoogle sitemapLinks back to the content – short help articles aren’t sexy enough given how short they are
16. How does your content look from a google search?We go through help via traditional portals. Mix things up every now and then and enter a different route via search. Can you find it? Do user keyword research based on user searches and structure your content with similar keywords
17. Problem is that as soon as you start including examples, you give away business context of how to use the application. This might be problematic because you’re recommending values or a specific use. This is much harder to do. Example here is with wordpress time stamp feature. You can explain how it works, but if you wanted to give context, you’re practically recommending strategy. Examples really bring documentation to life. They clarify complicated concepts soooo much. Each example clarifies by 20% or something.
18. Api examples thrive on code. Story: feedback from user who says we need way more examples.This screenshot is from a post by Sarah Maddox about how they redid some Google Maps API information.The problem is that providing code samples really gets to be tricky. Where do you get the examples? How do you validate the examples? How much is the person expected to know or not know?There’s a reason examples are often left out of the docs – they’re hard to create, especially those API ones.
19. Holy smokes. If there’s one advice that stands out, it’s to use visual communication tools.Every person who has ever given a visual design class at a tech comm conf. always says the same thing: you don’t need talent to create visuals. A stick man is pretty dang easy. Look at my person.The simpler the graphics, actually, the better. Draws less attention to the art and more attention to the point of the graphic. Draw any shape and put a label below it and voila, you have a recognizable shape. Combining text with images is probably the best invention for communication that has ever been conceived. Yet tech writers tend to thrive on text.
20. Subheadings are one of the greatest techniques for solving the long page problem:Easy to bolt on a new sectionAllows for page scanningSolve writers blockGood subheadings make it easy to grasp the info below itSubheadings add to your page’s SEO – allows keyword repeatability