The top 10 mistakes to avoid when starting an online help project

Transcription

1 The top 10 mistakes to avoid when starting an online help project Whitepaper The top 10 mistakes to avoid when starting an online help project Modern help authoring tools like RoboHelp are very powerful and offer great flexibility to authors. However, the same power and flexibility can get new projects off to a bad start. Some mistakes are plain silly, while others can lead to hiring the wrong author, picking the wrong output format, or letting a project spin out of control in ways that call for expensive rework later. The risk involved in employing modern help authoring tools has existed ever since they appeared in Thereafter, these tools became even more powerful and feature-rich expanding the scope for errors. Two changes in the recent years can magnify the effect of such mistakes: Test drive Adobe RoboHelp 9 Try the full functionality of RoboHelp 9 (as a part of Adobe Technical Communication Suite 3.5) in minutes without downloading the software. Tutorials are also included. To test drive RoboHelp 9 now, visit clients/adobe/techsuite. The internalization of help into an accelerating documentation process In the past, help authors could make mistakes and had time to find, fix, and learn from them. But today, tighter time-to-market and ROI (return on investment) demands are eliminating the authors ability to make and learn from mistakes. It s more important than ever to get it right the first time. The shift from viewing online help as documentation to content for reuse beyond the boundaries of the doc group Help authors now have to consider how their content may be used on a company web site, on mobile devices, or can be found via Google searches, and more. This shift adds technical, managerial, and strategic complexity to the once straightforward process of help authoring. With that background, this article examines what I consider the top 10 mistakes to avoid when starting new help projects. Interestingly, half of these are apparent in project management, and not development. The mistakes are: Project management mistakes Misunderstanding the present Not preparing technically for the future Not preparing managerially for the future Not coordinating the help authoring with other groups Not defining (and documenting) the development process Development mistakes Not developing mechanisms to support content consistency Not developing mechanisms to support format consistency Not revisiting project design in light of environmental changes Not planning to test QA (Quality Assurance) and usability Not planning to create an index Many of these mistakes can have serious consequences but, are fortunately fairly easy to avoid.

2 Misunderstanding the present Companies can make the seemingly logical choice to use RoboHelp for Word if they write content in Word, and RoboHelp HTML if they write content in an HTML editor. Today s online help options have been confusing for years and are often still confusing. For example, an old but common mistake is to misunderstand the difference between Web Help and WebHelp. They sound alike, but the first is a generic term for help on the web; the second is a specific browser-based output pioneered in RoboHelp in 1998 and now offered in one form or other by all help authoring tools. Another example is RoboHelp. It is available in two versions, RoboHelp HTML and RoboHelp for Word. Companies can make the seemingly logical choice to use RoboHelp for Word if they write content in Word, and RoboHelp HTML if they write content in an HTML editor. In fact, RoboHelp for Word is the original version of RoboHelp, introduced in 1991 to support authoring of the dead, pre-html Windows Help format. Adobe supports it for a shrinking group of users who have not yet upgraded, but RoboHelp HTML is the answer. Adobe launched its AIR Help format a few years ago which is now supported by most of the help authoring tools. AIR combines all the separate files that make up a WebHelp project into one for delivery. It s neater but users are required to download a help viewer to their PCs to run AIR Help. If users are not permitted to download applications to their PCs, AIR Help won t work. They will then have to switch to a different output. Switching isn t hard, but it may affect the help design or distribution plans, or one s credibility with the client. Make sure you understand your online help output options and how they fit into your users configurations.

3 Not preparing technically for the future Many authors use the common text formatting toolbar which is inefficient, slow, and often inconsistent...improved tools, like RoboHelp s Styles and Formatting Pod make it easier to use styles for everything. In the past, and even today, help authors got away with practices like not following coding standards or exploiting authoring tool peculiarities. Such practices were once done proudly, a sign that the author was a rule-breaking renegade. Today, they re increasingly seen as the cause of annoying and expensive-to-fix problems. For example, many authors don t use styles and CSS (cascading style sheets), instead they use the common text formatting toolbar for local formatting. But this is inefficient, slow, and often inconsistent. (It s hard to remember what shade of blue to use when formatting fifty subheads individually). Incase of no styles in the content, automated conversion tools have nothing to work with. But local formatting is familiar, so it s hard to abandon. Yet, using styles is more efficient, consistent, faster, and enables automated format conversion. Improved tools, like RoboHelp s Styles and Formatting pod, below, make it easier to use styles for everything text enhancements, like boldfacing, as well as traditional heading styles. A certain client was used to inserting graphics in a Word-based help project in a format that the authoring tool didn t recognize for some outputs. When the client generated output 1, which used graphics in format A but not B, the tool automatically excluded the graphics that didn t belong in output 1. When generating output 2, which recognized graphics in format B but not A, the tool automatically excluded graphics that didn t belong in output 2. It was a brilliant example of homemade conditionality, until the client upgraded to a new version of the authoring tool. The converter didn t recognize graphics in format B at all and ignored them, breaking the entire development model. Understand and follow good, up-to-date practices for the technologies and authoring tool you use. To emphasize the importance of doing this, consider the technical changes coming our way: Content created by writers using social media, to be integrated into the main content New outputs, like mobile, to be added to the single sourcing strategies The need to make online help visible to and searchable by the world through Internet. This means the content should display high on any search results list, which calls for getting involved in search engine optimization Such tasks and others will require automation and thereby standardization. This in turn needs thinking inside-the-box created by the rules of your authoring tools, their technologies, and good development practices going forward.

4 Not preparing managerially for the future It s easy to write a sufficiently detailed project description in a few days and update it after each change in the project. Very often, the documentation for a project that has to be updated or maintained is unavailable. The result is lost time during the update while the new authors reconstruct the project settings. For example, let us assume that a browser-based help project uses the!important parameter in a CSS (Cascading Style Sheets) to override inconsistent topic formatting. But the author who used that parameter never documented it because there was no time or the author assumed that he or she would always be on the project. That author leaves; the new one isn t a CSS expert and doesn t understand why the project is acting the way it is. The result is wasted time and money while the new author tries to figure out what s going on and perhaps even has to recreate parts of the project. As another example, assume that a previous author added the company logo as a clickable hot spot but never documented where to find the logo graphic. This isn t a major problem but leads to wastage of time, and such small things tend to add up. On similar lines, we may consider a more serious example. An author created context-sensitive help using a custom technique to connect the help to the application but didn t document that technique. That author and the programmer who helped set up the technique are now gone, or are on another project and don t have the time to help the new author. Document the project and update the documentation any time the project changes either technically or structurally. We often refrain from documenting projects on the grounds that there isn t time. But it s easy to write a sufficiently detailed project description from scratch in a few days and update it after each change in the project. It s a small thing but a big part of controlling projects. Not coordinating the help authoring with other groups Help authoring used to be self-contained aside from asking Engineering about questions or contextsensitivity integration with the application or review comments. But once help became HTML-based in 1997, more and more groups and standards began affecting help projects in ways that may be important but not always obvious. Help authors have to interact with these groups and follow these standards. If not, some technical decisions may not get made, or may get made in ways that are detrimental to the interests of the help projects. For example, RoboHelp has a W3C(World Wide Web Consortium)-Compliant Topics option. It may be necessary to talk to Engineering to decide if a project needs to use it. Engineering may not have an answer, in which case the help authors can take the technical lead on the issue and raise their credibility with Engineering. We may cite a few more examples. Many help authoring tools have a Mark of the Web option. Once again Engineering may be questioned about its use. If there happens to be no answer, the help authors may have to take the technical lead in this case as well. Similarly, HR may be asked whether to support accessibility in help; Marketing can be questioned about adding Flash movies to help projects; IT, about whether to use SWF or some other format and why; management, about the company s technical direction to determine whether a move to mobile is coming and how that might affect the version of CSS supported by the help projects. Determine who is affected by and who and what affects the help projects and factor it into the projects. Help authors have to be prepared to take the initiative because some of the other groups may not think of taking it to the doc group.

5 Not defining (and documenting) the development process Develop and use project checklists as it s risky to trust memory. Help authoring has many steps and it s easy to forget a few during development or when it s time to publish the final version. The result being time wasted in having to go back to correct problems, embarrassment when users find a problem that was overlooked, or unnecessarily complicated development. For example, one embarrassing mistake is to send out the final version of the help with a spelling error. It s easy to fix by using spell-check. But many authors fail to do this. We know the risk but we tend to overlook that step. An irritating problem when authoring is creating topic templates and applying them to topics only to find that some parts of a template were not applied. The reason being that different parts of a template behave differently when used on existing topics versus new topics. But it s easy to forget this. Develop and use project task checklists. It sounds silly, especially for experienced authors who know their projects. But it s risky to trust memory. Experienced airline pilots use checklists, so should help authors.

6 Not developing mechanisms to support content consistency Different authors may write procedure topics differently for the same project. This problem can arise even on projects with one author. One of the hardest tasks in help authoring is developing structurally and terminologically consistent content. Without that consistency, the help is hard to use because readers have to take time away from understanding what the topics are saying to understanding how they re saying it. For example, different authors may write procedure topics differently for the same project. The information is available but readers have to figure out different structures for each topic (like using an system that sometimes asks for the recipient s name first but may ask for the subject or cc names first). It s obviously inefficient and this problem can arise even on projects with one author. Let us consider the help for a product from a company that grew by acquisition. Different authors use different names to refer to the same thing (in North America, a sandwich made of cold cuts on a tubular loaf of bread is called a hoagie, grinder, sub, hero, wedge, po boy, and more). Different terms make the content hard to search. A user who refers to a task as A and searches for it in a help system written by an author who calls that task B won t find any hits and will conclude that the help is useless. This can be made up of two parts. First, develop and use topic templates to get structural consistency between different topics of the same type procedure, concept, reference, etc. Developing templates is tedious but fast and templates can be used in and amortized over multiple projects. To create the templates: 1. Examine a representative sample of your help content and sort it into categories procedure, concept, reference, troubleshooting, show-me, and so on 2. Review the samples in each category to see what elements they contain. For example, concept topics might contain level 1 and 2 heads, body content, graphics, and related topic lists 3. Organize the elements into standardized structures, such as topics always starting with a head 1 4. Check for inconsistencies between the standardized structures and other examples of the same topic type. For example, if the standard concept topics always have a see also list but another concept topic does not, does that mean the author of that non-standard topic made a mistake or that the see also list is optional? This is setting the rules for structures that, in turn, form the basis of the topic type templates 5. Use your authoring tool to convert the paper templates of step 4 to live templates embedded in the authoring tool interface. This makes it easy to use templates when creating new topics. The result is greater structural consistency There is another benefit to creating templates this way. Elements defined for each topic type are also the elements whose format properties must be controlled. Identifying these elements this way sets the basis for creating a CSS. Second, see if the tool has features that help create consistent content, such as variables. For example, a variable called sandwich name with a value of hoagie can consistently insert the word hoagie for us. We don t type the name but simply tell the tool to insert the name of the variable hoagie, until we change the variable value, at which point the name changes everywhere or an auto-complete feature that reads the first few letters of a word as we type it and offers to automatically complete it.

7 Not developing mechanisms to support format consistency Styles and a CSS are far more efficient than the text formatting toolbar but call for a big change in our working habits. Similar to the need for content consistency is the need for format consistency. I raised the issue of styles earlier as a management issue but it s also a development issue, and important enough to revisit for emphasis. Format consistency refers to content display font, size, colors, etc. but it goes beyond text to issues like graphic position and size control, and table formatting. This consistency is not only important for authoring and reading, but also to follow online authoring trends towards removing all formatting from documents and putting it in the CSS instead; the only thing in the document is the structural and semantic coding. The less formatting in the body of the document, the easier it is for today s authors and tomorrow s conversion tools to understand and process that document. For example, as noted earlier, styles and a CSS are far more efficient than local formatting using the text formatting toolbar but call for a big change in our working habits. This, under any circumstances is hard and styles can be particularly difficult. Their logic isn t always clear and the CSS standard is often being revised by the W3C, it may not be supported consistently by different browsers or different versions of the same browser. Yet, the following abilities are so useful that there is no good reason to not adopt CSS: to set and change content formatting across an entire help project to semi-automatically reformat content for display on different devices and outputs using one CSS to perform local text enhancements like boldfacing using styles (especially in the light of traditional formatting methods that W3C and HTML5 have started to deprecate Help authoring tools are also adding support for table style sheets. These use the same format features of a regular CSS but provide an easy visual way to create them. The tools also add useful table style automation mechanisms, like the ability to delete old local formatting that is blocking a table style with one mouse click and without going into code. Develop a CSS and as many table style sheets as needed, teach authors how to use them, make their use mandatory, and prohibit local formatting. Keep it simple; the harder the styles are to use, the less they will be used. You don t have to become an expert on CSS or CSS3, but it does help to understand the concepts. I consider the best reference on the subject to be the book Cascading Style Sheets: Designing for the Web (3rd Edition) by Hakon Wium Lie. Also stay updated to speed on changes in the fairly new CSS3 standard by checking any book on the emerging HTML 5 standard.

8 Not revisiting a project s design in light of environmental changes Check periodically about what may be changing in your distribution or configuration environment. If this is your first help project, you ve got a clean slate. But if this is not your first project, past experience can actually be detrimental. There is a tendency to repeat what was done in the past projects even if it may no longer be appropriate due to changes in the authoring and delivery environment (the term environment refers to the technical environment in which the help must operate the platform Windows, Mac, UNIX, etc., the browser(s) IE, Firefox, Chrome, etc., and location local, network-drive, or server). For example, many HTML help projects use a browse sequence feature that lets users advance or back up through topics sequentially, like turning pages in a book. It enables this feature with left and right arrow icons. But, when the environment changes to browser-based, users see arrow icons on both the browser toolbar and the help window, as shown below. They look similar but actually do different things and can leave readers confused or lost. Check periodically with Engineering or IT about what may be changing in your distribution or configuration environment. Is the company shifting its software to a serverbased model rather than running locally on users hard disks? Is the company changing the browser and version needed to run a web application? Do you want to enforce the code standards for syntax compliance on new browsers under strict mode versus the looser quirks mode? Some environmental changes won t affect help authoring, but some may. You need to find out before starting the authoring.

9 Not planning to test QA and usability Help authoring tools watch for broken links and automatically fix them but some can slip by, so one crucial task in a project is checking for and fixing broken links. Very often, we create help projects with no idea whether readers can use them. There are actually two sides to this QA, whether a particular feature works at all and its usability, whether readers can find and understand how to use that feature in the first place. For example, links can break during authoring. Moving or renaming a topic can break links that point to that topic. Help authoring tools watch for broken links and automatically fix them. They do an amazingly good job of it but some broken links can slip by, so one crucial task in a project is checking for and fixing broken links QA. It s tedious but necessary; the more broken links in a project, the more trouble users have with it and the more credibility it loses. I recommend setting up a series of rules for the types of errors to accept in a project. Broken links Must correct Inaccurate information Must correct Display and formatting problems Should correct if time permits and if readers notice them. (It is possible to make formatting errors, like misaligned hanging indents in lists that readers may not even notice. In that case, you might ignore the error) Coding errors that violate syntax but that readers may not see Should correct if time permits and strategic direction requires. (Code validation tools will find many errors that users will never see but that may cause authoring problems if a project has to be updated to a new version of an authoring tool or converted to a different output format. In that case, you have to fix the error. Talk to management and Engineering about direction) These errors are fairly easy to find. Ideally, the QA group will find broken links, although it often falls to the authors to review their own material by clicking on each link to be sure it works and goes to the right target. The review should find inaccurate information, plus display and formatting problems. Finally, you can use validators like the W3C s HTML/XHTML validation service at to find coding errors (the problem lies in deciding what to do with the results of a validation scan). But QA is only half the battle. The other half is usability. The concept of usability is simple readers can use the help system s navigation features to quickly find the information they need. It sounds simple. Readers should be able to find what they need between links, a table of contents, an index, and search. But there may be no index. The table of contents is rarely good for finding detailed information. The search engine may not give the results that readers expect like searching for hoagie, but not finding it, and not realizing that you have to search for sub. A link may take readers to the top of the correct topic but then force them to read down four screens to find the specific material they need. If usability is bad, readers may ignore the help and just ask the person in the next cubicle, call tech support, or do a Google search. Each of these cases reduces the credibility of the help and the value of the development effort. This comprises two parts. First, be sure the project gets gets reviewed by a subject matter expert for content accuracy and formatting, the QA department for programmatic elements, and the QA department or Engineering for the coding. It s never this clean in practice but the closer to this ideal, the better. Usability is more difficult because it often has no functional home in the company. Everyone agrees that help should be usable but no one is officially designated to make sure it is. Many companies also skip usability testing because of the time and expense needed to do a statistically valid job. But I recommend to clients that, if nothing else, they create a few simple cases that ask test subjects to answer a question by using the help, then watch them try to find the answer to see if they can, how long it takes, and how painful the process was. Repeat this with a dozen people. You may not get statistically valid data but you can get a lot of good, often painful, feedback.

10 Not planning to create an index is that search won t always find what readers are looking for...the index solves these problems. Authors often create online help with no index, assuming most readers will navigate using the search feature. In many cases, this is because we don t like indexing or think there isn t enough time to create an index. This has always been true in help authoring but has been aggravated in recent years by the spread of Google. Why create an index when users will just search? [this attitude seems to have spread widely enough that the epub ebook standard from the IDPF ( officially does not contain an indexing feature, although this may change]. is that search won t always find what readers are looking for (search for hoagy when the help refers to sub ). Help authoring tools offer a way around this problem by letting us add search synonyms, specifying hoagy as a synonym of sub. This way, searching for hoagy will find the topic called subs. But this result may seem wrong. I searched for hoagy, why did it find sub? The answer of course is that hoagy and sub are synonymous, if the reader realizes that. But some readers may not realize that at first and just think the result was a mistake. A search can also find too much. Googling English setter breed characteristics returned 3,920,000 hits, for example. Which hit should you use? You ll probably find the necessary information in the first ten or twenty hits, but that means you may have to waste time opening ten or twenty hits. The index solves these problems. First, index synonyms actually tell readers what term is the synonym e.g. hoagy, see sub rather than requiring readers to realize that hoagy and sub are synonymous. Done well, the index is also more focused than a search because the help authors specify the target rather than leaving target selection up to a computer algorithm. Rather than a search for English setter returning almost 4 million hits, the help author can specify the one hit to return. Simply create an index. At a minimum, make each topic s title an index entry. Better still, make each title and its inverse index entries. For example, for a topic called Print Dialog Box, create the index entries Print Dialog Box and Dialog Box, Print. If your authoring tool has an indexing wizard like the one in RoboHelp (an index term selection screen is shown below), use it to create at least a minimal index for the first release of the help and then update and extend the index with each new release of the help. You ll slowly but surely build a workable index whose benefit you can then try to measure in usability tests.

11 Summary Anyone involved with help authoring has made at least some of the above or other mistakes. (In 1987, I built a help system for MS-DOS using a software that didn t support an index, only to add an index manually when I realized I couldn t find some information in my own help system). But in those days, there was time to make mistakes, understand them, and learn from them. That is no longer the case. Today, doc groups are smaller, budgets and schedules are tighter, and there is less latitude for error. We will make mistakes help authors are human beings in a fast-moving technical environment. The important thing is to learn from our mistakes and those of others (preferably) and not repeat them, like the mistakes described in this paper. About the Author Neil Perlin has 33 years of experience in technical communication, with 26 in training, consulting, and development for online formats and tools like WinHelp, HTML Help, RoboHelp, and more. Neil spent six years at Digital Equipment Corporation, then became a partner in a hypertext consulting firm in the late 1980s. In 1990, he formed his consulting firm, Hyper/Word Services. Neil writes columns and articles about online help and documentation, and is a popular speaker for STC and other groups. He is Adobe Certified for RoboHelp, and offers training, consulting, and development services for online content methodologies like structured writing and single sourcing, mobile, XML, and related tools like RoboHelp. He can be reached at nperlin@concentric.net, Adobe Systems Incorporated 345 Park Avenue San Jose, CA USA Adobe, the Adobe logo, and RoboHelp are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All other trademarks are the property of their respective owners Adobe Systems Incorporated. All rights reserved. Printed in the USA /12