Th e top 10 mistakes to avoid when starting an online help project Whitepaper Th e 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 1991. 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: • 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 Test drive Adobe® RoboHelp 9 today, tighter time-to-market and ROI (return on investment) demands are eliminating the authors’ Try the full functionality of ability to make and learn from mistakes. It’s more important than ever to ‘get it right the first time’. RoboHelp 9 (as a part of Adobe Technical Communication Suite 3.5) • The shift from viewing online help as ‘documentation’ to ‘content’ for reuse beyond the in minutes—without downloading boundaries of the doc group the soft ware. Tutorials are also included. To test drive RoboHelp 9 Help authors now have to consider how their content may be used on a company web site, now, visit www.runaware.com/ on mobile devices, or can be found via Google searches, and more. This shift adds technical, clients/adobe/techsuite. 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. Misunderstanding the present The problem Companies can make the Today’s online help options have been confusing for years and are often still confusing. seemingly logical choice to For example, an old but common mistake is to misunderstand the difference between Web Help and use RoboHelp for Word if they WebHelp. They sound alike, but the first is a generic term for help on the web; the second is a specific write content in Word, and browser-based output pioneered in RoboHelp in 1998 and now offered in one form or other by all help RoboHelp HTML if they write authoring tools. content in an HTML editor. 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. The solution Make sure you understand your online help output options and how they fit into your users’ configurations. Not preparing technically for the future The problem Many authors use the common In the past, and even today, help authors got away with practices like not following coding standards or text formatting toolbar which exploiting authoring tool peculiarities. Such practices were once done proudly, a sign that the author was is inefficient, slow, and often a rule-breaking renegade. Today, they’re increasingly seen as the cause of annoying and expensive-to-fix inconsistent...improved tools, problems. like RoboHelp’s Styles and For example, many authors don’t use styles and CSS (cascading style sheets), instead they use the Formatting Pod make it easier common text formatting toolbar for local formatting. But this is inefficient, slow, and often inconsistent. to use styles for everything. (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. The solution 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. Not preparing managerially for the future The problem It’s easy to write a sufficiently Very often, the documentation for a project that has to be updated or maintained is unavailable. The detailed project description in result is lost time during the update while the new authors reconstruct the project settings. a few days and update it after For example, let us assume that a browser-based help project uses the !important parameter in a each change in the project. 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. The solution 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 The problem Help authoring used to be self-contained aside from asking Engineering about questions or context- sensitivity 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.