Are TOCs required in a “Search Centric” World?
Let me put my cards on the table here. I am a man of a certain age with many years experience in using and producing help files. I hark back fondly to the days when a Table of Contents was the only means of navigating. All my documentation has a Table of Contents and I insisted that a specific set of rules be included in our Style Guide on the subject. All of this aside, time marches ever onwards and I believe it is right for you to have your say on the matter.
This post was inspired by a twitter poll run by RJ Jacquez, Adobe’s Senior Product Evangelist, which asked whether we see a TOC as being a required element of a help file. There is no doubt that younger, more technical users interact with help files in a different way than I did when I was their age. Technology has advanced and searching offers many user benefits that simply were not available years ago. Demands on our time mean we want a quick and easy method of finding what we want. But to answer the question of whether a TOC is required, we need to address the following questions:
- Is a search facility the only method a user needs to find content?
- Does a search give the user 100% of the required information?
- If it doesn’t, how do they find the rest?
The answer to the first question is, “It depends.” The mantra of any technical communicator is, “Know your audience.” If they don’t want a TOC, never use one and are paying for you to deliver the end product, you pretty much have your answer right there. However it should also be part of our role to educate our users where required. Part of that is should be extolling the advantages of the TOC (and Index for that matter) and how it can be used. This leads me nicely onto the second question.
So you want to find out how to do something, you open the search tab and type in a question. As if by magic, a long list of results is returned. Problem solved! Or is it? Which result do you look at? Does the result at the top of the list provide the required information? Do you have sufficient information visible to make a judgment? All of these questions highlight everything that is wrong with search functionality. By its nature it is subjective. Each search tool’s algorithm works in a particular way and there is nothing you can do to change it. Perhaps you can include keywords in your content that will be picked up, but that’s about it. It is just the nature of the beast that you have little control over what it returns.
So you have a list of 10 topics to choose from with only a limited amount of information available to enable you to make the right decision. You click a link and read the content. As luck would have it, it provides you with the answer and away you go. Trouble is, five minutes later you get stuck again further down the process and have to repeat the process all over again. If only there was a means of identifying where you were inside the help file’s structure. Then you could look inside that part of it and see if there was something more likely to meet your needs. What? There’s no TOC? Expletives deleted!
Is a Help File Index on life support?
I have to admit to asking this question with my tongue placed squarely in cheek. I have always been someone who has ensured that people know of the value of an index and have taught others about how to index effectively. I have fought to ensure that sufficient time is allowed as part of a project to index properly rather than just an hour or so at the end. However despite all of this, I can’t help feeling that the importance of an index is subsiding. If you think I am overreacting, consider the following.
Over the last few weeks, I have been helping a Technical Writer who had been struggling to update a legacy project that had been upgraded from RoboHelp X5 to 8. As they were themselves new to RoboHelp there were loads of questions relating to the product’s use. We have got to a state where things are almost ready to publish when the subject of indexing emerged. It was clear that they were more than a little confused by the functionality offered to index topics in RoboHelp 8. On the face of it the RoboHelp interface for indexing topics has not changed very much from the early versions. You add keywords and sub-keywords, assign these to topics and these appear as if by magic in the Index tab of your help file. Even the Smart Index Wizard hasn’t changed and can be used to index if you really want to suffer a nervous breakdown.
extended, you can now add keywords to a topic, which are therefore searchable, yet are not themselves displayed in the Index. What gives? Take a look at your Topic Properties. As well as the familiar Index tab, take a harder look at the General tab and the “Keyword” field. This is the field that allows you to specify keywords separated by commas that users can search for to find the topic.If this doesn’t convince you of the decline in importance of an index, consider the advent of Adobe AirHelp. It celebrated its second birthday this week and has caught the imagination of many. AirHelp is an output option in RoboHelp 8 and it offers many advantages compared to other outputs, even when compared to WebHelp and FlashHelp. The Adobe RoboHelp help file is just one example of this output type, albeit a tailored one, but if you have looked at it you will notice there isn’t an index in sight. Nada! Nothing! There is a search field but with the ability of the search to “find” index keywords, it can be argued that it really isn’t required.
Of course whether an index is available in your help file is entirely down to you, but the advent of a younger, more googlised user base has seen users of an index decline. The index may not be dead yet, but I can’t help feeling that it will continue to decline to the point where more and more Technical Writers will stop creating them. It will be a sad, yet inevitable, moment if that does happen.
A review of the Noughty’s – Part 1
David Farbey tweeted recently on how he had noticed how everyone had started summarising the years 2000 to 2009. As the end of a decade is such a momentous event (?) it is probably inevitable that editors struggling for a story during what is called “the silly season” turn to an easy fix. Not to be outdone, and honoring the fact that I have, officially at least, been a Technical Writer since 1999, I offer my own completely unscientific review of how the technical communication world has changed in the last ten years.
Note: I have split the review up into parts. Part One covers the migration from static offline help to user generated on line help.
Help….WinHelp!
In the good ol’ days when I had loads of money (pre-marriage) a full head of hair (also pre-marriage and pre-work) and technical communicators were easily pleased, I produced my first piece of documentation in WinHelp format. The sleek, familiar user interface made my first foray in technical writing a relative breeze. Oh how the mighty has fallen. One look at a WinHelp project these days makes me wince. OK there were some good things about it (e.g. non-scrolling regions) but on the whole it just doesn’t cut it in today’s feature rich, customer interaction environment. They just didn’t provide enough functionality for the discerning user and we Technical Writers just had to go. Whilst they are still used to this day, despite Microsoft’s best efforts, they are few and far between having largely been relegated to legacy help files for old and tired applications that have yet to be sunset or assigned a budget to upgrade.
The step to Microsoft HTML Help brought with it a rich stream of possibilities to improve user content. Like anything new it required a certain amount of getting used to, not least the fact that it was coded using HTML, but on the whole it was a huge step forward. Just the fact that you weren’t using MS Word as your editor was surely reason enough to change. However rather ironically a number of Help Authoring Tools surfaced that allowed you to generate the required HTML from a MS Word like interface. Now you could produce HTML in from a familiar interface without the vagaries of the familiar application! All of a sudden you could produce your HTML code without ever coding anything. Whilst it is possible to create your HTML topics in Notepad (I know someone who does even now) tools like Adobe RoboHelp provided an MS Word like user interface with which to produce your works of art. Microsoft HTML Help also brought with it a range of new gadgets and tools that allowed you to enrich your content (e.g. DHTML, browse sequences, forms, etc.).
However arguably even Microsoft HTML Help has its day. Whilst CHM files are still widely used and probably will be for sometime to come, the arrival of the Internet brought with it the need for online content. With the concept of a CHM being that they are designed to run on a local PC, we often used to see if we could bend the rules by placing them online. This worked to a degree but the incessant need for 100% security soon drove a dagger into any CHM file located online. They were deemed to be a risk and after Microsoft released Security Update 896358 in June 2005 they could no longer be effective unless located on a local drive.
Online help became the buzzword of the day. Outputs like WebHelp and FlashHelp gave Technical Writers the ability to change from being purely content providers to someone who could start to change the look and feel of the documentation we provided. The advent of skins allowed us to design the interface to the documentation as well as the documentation itself. What is more these outputs were more flexible allowing us to place them on internal intranets or an external site. Now our users could access the very latest documentation without having to install or upgrade an application. What is more, they could do so from anywhere provided they had an internet connection. All of a sudden staff in the field became enabled to find information quickly and easily.
Now I can’t let a review of output formats of the last ten years go by without mentioning my nemesis. For a short period after taking on my current position I was tasked with producing JavaHelp. The misguided decision made before I joined that this was the required output type because our application was written in Java was soon reversed! As soon as I pointed out the long list of its limitations and more importantly the negative feedback we were getting from users, particularly around searching, we managed to get agreement to change. If anything, it was this decision that highlights the changes that have occurred throughout my career. Namely that the documentation function has gone from something that costs, to something that can add real value to the product. The powers to be can see that it eases pressure points and can be a real difference to the overall user experience.
Indexing. The line in the sand.
Call me old fashioned but I still believe a good, well structured index is more useful than any search facility in a help file. The search algorithms employed just don’t quite cut it for me which is why I really do believe that taking the time to index is time well worth spending. Of course indexing is not a quick and easy fix, although I’ve seen many an index that indicates there are people out there who think it is!
Compiling an index requires a particular type of methodology. If ever there was a time when you had to get inside a user’s mind, this is it. You have to think of why the user may want to see this topic and what keywords are they likely to search on to do so. Will they use an acronym or an abbreviation? What does the topic contain? Does it have ancillary information that a user may require? If so it needs indexing.
It is natural for Documentation Managers to balk at the time it takes to index a help file properly. This is especially true when the expectation is that the help has a search facility. Why should you spend a week indexing a help file when you have an adequate search tool that allows users to find what they want with only minimal effort from the Technical Author.
This short sighted view overlooks two vital points. Firstly, many users still prefer using the index for finding help. The Google generation may be alive and well but it hasn’t quite taken over yet. An index is quick and easy to use and is more likely to provide accurate results if the author has taken the time to index correctly. The second point is that various forums are awash with users having questions and/or problems with the database of search results provided by their HAT. So much so, that they often use an alternative. My friend Peter Grainge has an article on his website that shows how to employ ZoomSearch as part of your WebHelp output.
You could employ the sneaky technique of indexing and then renaming the index tab to “Search”. The users think they are searching when in fact you’ve duped them to use an index. I’ve heard of this approach being used but it should only be used as a last resort. To me indexing is an art form but one which is absolutely required. Any lines in the sand of resources must be drawn after any full and proper indexing has been resourced.
Adobe Community Help. Did you know about it?
It started with a discussion about the advantages and disadvantages of WinHelp (during which I got all nostalgic for non-scrolling regions) went on to a discussion on how the Adobe Community Help allows users to add comments to the help, and finished with a futuristic mind sharing of how this could be developed in the future. In effect those three discussions covered the full range of help delivery systems that I have worked with since moving formally into technical communication. More “Career in the Life” than a “Day in the Life”.
The documentation Holy Grail
It was the discussion on the Adobe Community Help though that generated more interest than most. For as long as I have been in the industry, the requirement for users to add comments to the help has been a kind of documentation equivalent of the Holy Grail. Wouldn’t it be useful if they could add links to wikis, websites and blogs? How about if they could post tips and tricks on how to get more out of the product? Increased productivity and user satisfaction: now that is worth its weight in gold.
The Adobe Community Help provides just that allowing you can post your views, comments and information related to the help content shipped with the product. We all know that no help documentation is perfect, so why not get some satisfaction in helping improve the user experience for others. So far the Adobe Community Help programme has resulted in thousands of improvements in the documentation shipped with Adobe products. That has to be a win win for everyone.
OK I’m in. How does it work?
First of all it is worth stating that only more recent Adobe product versions (e.g. RoboHelp 8, FrameMaker 9, Captivate 4, etc.) have Adobe Community Help. You’ll be able to tell instantly whether your product help file has it, as the look and feel will be very different from what you may be used to. There is no more formal tri-pane navigation for a start. Instead there is a mini-TOC at the start of each section linking you to the relevant content.
However it is the comments feature that really sets it apart from anything that has gone before The top of the topic indicates whether any comments are present. If there are, clicking on the link displays them instantly. For this you do not need do anything apart from open the help and click the link.
If you want to add a comment, you’ll need an Adobe logon. This is the same logon as used elsewhere on the Adobe site, so if you have ever posted a forum query, registered for an Adobe event or purchased an Adobe product online, you’ll already have one. Just sign in and the comment functionality becomes active.
To add a comment:
That was easy. Now what?
You may notice that your comment does not display against the help topic immediately. This is because all comments are held in a moderation queue. A team of moderators, normally power users of the relevant product rather than Adobe staff, check the queue and approve or reject as appropriate. As soon as your comment is approved it appears for all to see.
OK. What are you waiting for?