On the HATT list today, there was this post:
Howdy all! I've been away from corporate tech writing for a few years, now getting back into it. Starting in the mid-90's, I used RoboHelp, and then later Madcap Flare. Was happy with both. Nowadays, with web apps, API's, and mobile becoming more and more popular, it seems like the trend is towards Help being simply a group of Web pages with topic links on a home page or in a panel on the left side and maybe a search feature (if you're lucky). Here's an example, the Yahoo User Interface framework (YUI) API documentation:
http://yuilibrary.com/yui/docs/api/
My questions:
1. What are the tools being used for this kind of help? Is it simply a matter of making Web pages in a program like Dreamweaver and adding some clever JavaScript, or are there newer tools geared towards this kind of "Web site Help" other than the traditional ones I mentioned?
2. What do feel are the pros and cons of this type of approach? What are some examples of your favorite sites of this type?
3. I'm sort of regretting the lack of an Index in these systems which I think is the best way to find stuff quickly if it's well-designed. Has the index gone the way of the dinosaur?
Alastair Dent, a member of HATT I've probably quoted previously on this blog, responded with this:
*decent* help hasn’t changed much in the features:
Sensibly-structured contents (usually collapsible tree is preferred).
Full-text Search
Hyperlinked.
Indexes have been pretty much replaced by full-text search.
Robohelp and Flare are capable of delivering this, either via a browser or a viewing format such as chm engine.
And then I chimed in with this:
I agree with Alstair that the basic principles of online Help have not changed, especially about the index. None of our Word docs that we distribute as PDFs have an index. The users simply press Ctrl+F, type what they want to find, and they’re off.
Because I hadn’t heard of “YUI”, I briefly looked at the link you provided. I think it’s a good example of documentation. I love the text on http://yuilibrary.com/yui/docs/test/ in the “Using Test Cases” because it goes beyond ‘this is how you set up a test case.” It talks about the impact of doing what the documentation is telling you to do with text like this:
|
Regardless of the naming convention used for test names, each should contain one or more assertions that test data for validity.
|
At work, we are focusing more and more on this type of “impact” information and focusing less on “click this, do that” information. It’s not one type being more important than the other, but it’s understanding, as a technical writer, that when I tell the user to set something up in the system or to do something in the system, there’s an impact.
Here’s an example of what I’m talking about. If you open the online Help for Word 2013 and type “bold” in the search, this is the text for the first search result:
|
"Bold" is under "Home/Font"
Click Home > in the Font group > click Bold.
Look for this icon:
B
More about "Bold"
Make your text bold.
Another way to do this
Hit the Alt key. Then type H1 (one key at a time).
Other places you can find this command
Click File > New > New Blog Post > Create.
Click Blog Post > in the Basic Text group > click Bold.
|
First of all, “hit” the Alt key? Hit? Really? (shudder)
Second of all, where does that text tell you that to apply text to a word, like unhelpful, you have to select the text first?
But let’s say you figure that out because when you don’t have text selected, nothing happens.
Beyond all of that, what would be helpful is to have some text about what happens after you apply bold to text. If you find the icon and figure out you have to select the text first, what impact does that have on your document?
At a “higher level” than clicking bold, the impact by doing so within your document is you’ve just made what could be automated into a manual task. What does that mean? Well, Word has a powerful capability to create a style and it can make changing the appearance of text automated. What’s a style? It’s a way to define the appearance of text, including whether the text is bold or not. After you define the style, you can apply that style to any text you want. Go further. After you define a style within a template and apply that template to your documents, you can change the style definition in your template and that will ripple into your document and change the appearance of all text that has that style applied. You don’t have to do *any* manual work.
Why does this type of “impact” information need to be on websites that talk about Word and styles and templates? Why isn’t it included in Microsoft’s documentation? Because you get unhelpful information like the following when you search for “styles”:
“Open the Apply Styles dialog so that you can quickly type the name of the style you want to use, or select it from a list.”
How do you create the styles that display in this list? Where’s the conceptual information?
Now, all that said, do you have to use styles? Does every user that needs to apply bold to text need to know about styles?
Of course not. But when documentation is for all levels of users – my mother-in-law up through me – shouldn’t all levels be somehow accommodated? I don’t even need to create a style if I’m writing a letter of complaint to an external hard drive manufacture because the blue light on the external hard drive that was purchased in November 2013 now won’t light up after it’s been plugged in and when you do contact their tech support, they tell you they can replace the hard drive but all the data on it will be lost, including your 30,000 music files. If I’m writing that letter, no, I don’t need styles.
All of that to say, my advice is to find a way to write about the task you are telling the user to complete in the system at a higher level. If you see an icon B that has hover text that says, “Apply Bold” why do you need to tell the user in your documentation, “to apply bold, click the B.” Go beyond the ‘hit this, do that, click Save text that we see everywhere, *that* is useful documentation. Go beyond:
|
Clear all text formatting
In Microsoft Word and Microsoft PowerPoint, you can easily clear all formatting (such as bold, underline, italics, color, superscript, subscript, and more) from your text and return your text to its default formatting styles.
Select the text that you want to clear the formatting from.
On the Home tab, in the Font group, do one of the following:
In Word, click Clear Formatting.
In PowerPoint, click Clear All formatting.
|
And say that before you clear all text formatting, you probably want to verify that you actually have styles applied. If you have a 200 page document that is 100% Normal style with manual formatting, clearing the formatting by the above procedure is really going to make your life hell if your deadline is 3 PM and it’s now 1 PM.
Have fun and I’m getting back to my work now.
No comments:
Post a Comment