In a previous post, I started to explain my approach to help authoring. I’m trying to flesh this out into a more developed and detailed — but not too long — statement about how I do help. This information would be useful both to project managers as well as other writers I work with. I would appreciate any feedback.

Help Strategies

Because users have different skill levels and learning styles, help material needs to be multimodal in its approach, providing content not only in written format, but also through videos, illustrations, and the interface. With this approach, learning materials for a software application typically include the following:

Videos. Videos are usually brief screencasts that focus on a specific task. As screencasts, the videos are voice-narrated and focus only on the screen, without actors or scenes. The screencasts are short, such as 1-2 minutes, and are created almost entirely by the technical writer. This keeps production costs down while allowing for updates as the application changes. New users, especially visual learners, will typically view a series of videos to become familiar with an application. Videos aren’t meant to address advanced topics or edge cases, but are targeted at new users who prefer to learn by having someone show them how to do tasks.

Quick reference guides. Quick reference guides are usually two to eight page guides containing brief instructions in a visual way. These guides often contain screenshots with callouts and other explanations. The quick reference guides can also include concept diagrams, workflows, and other illustrations to help users understand the application quickly. Text in quick reference guides is brief and compressed, providing more of an overview than specific how-to detail. The basic idea of a quick reference guide is to give the user just enough information to get started in the application. This type of help material appeals to users who prefer some information in a brief, easy-to-digest way as they first jump into an application. Like videos, quick reference guides are targeted to new users.

How-to guides. How-to guides are lengthier printed guides that expand on the application in a more elaborate — but not comprehensive — way. A how-to guide is meant to be read, not merely referenced, and will focus on many concepts and capabilities within the application. These guides are a subset of the total documentation, with topics selected and integrated in such a way as to produce a readable booklet about the software application. These guides are usually single sourced from the online help and crafted in a way to make them pleasing in a print-reading experience. How-to guides are intended for users who want a more in-depth grounding in an application.

Online help. Online help is a browser-based HTML format for help content. Online help is the most comprehensive collection of topics, intended for reference and searching more than anything else. Online help is meant for users who have specific questions or need to search specific how-to’s (often advanced topics) about the application. Online help isn’t intended for people first learning about an application, because the topics aren’t necessarily grouped in a sequential or linear way. Each topic is modular and can be accessed and interpreted independently of other topics.

Interface text. Interface text includes all the language within the interface, from button names, page titles, and error messages to other instructive and navigational text the user interprets to use application. These interface tips and guides are important for users as they explore the interface and learn by doing. Interface text can also take the form of on-screen help text (often shown in hover tips) or as context-sensitive help, which shows a topic relevant to the current page. Interface text accommodates users who prefer to learn by doing.

Help Content

Access to users. Apart from the format, the content of the help material needs to be relevant and useful. In order to produce relevant content in a language and organization that makes sense to users, technical writers need to understand the user’s environment, vocabulary, and tasks. As such, technical writers need access to users. The access could come through phone calls, observations of users, or other interactions. Based on interactions with users, the technical writer may create personas and scenarios to create better help. Personas and scenarios can expand the perspectives from which a technical writer sees an application.

Multiple perspectives. The paradigm of a single author working from a single perspective, usually as an outsider to the actual business context of the application, is a paradigm that typically fails, since no one person can know all the information needed to help users. Contributions from multiple perspectives — from project stakeholders, project team members, community volunteers, and end-users — will help the content reach relevance and usefulness for a larger number of people. The importance of collaboration requires an approach that facilitates multiple authors and distributed ownership.

Editorial roles. Because of the need for distributed authoring, subject matter experts may often be content contributors. In these cases, the technical writer acts as an editor to help style and review the subject matter expert’s content. Other times, end-users themselves may contribute toward the content. User contributions should not be discouraged, nor should it be difficult for users to contribute or provide feedback. Heavy content collaboration may be facilitated through a wiki platform, but not necessarily. Other methods for interacting and content sharing can also be employed, such as with forums or comments below topics. In each case, the technical writer either edits or facilitates the content rather than creating it from scratch.

Perpetual beta. When the application is released, content is not finished. Even though content may be in a semi-complete state, we can never anticipate all the gaps, needs, quirks, and issues that users will encounter pre-release. For this reason, content needs to be published in a perpetual beta state, that is, with the ability to continually update the content even after release. As such, the help content should be stored separate from the application code to avoid release-window-only time frames. Technical writers should be able to update any help content on the fly as needs arise. Because help is usually stored on another server, applications requiring login should employ single-sign-on to reduce a secondary login windows.

Agile feedback loops. Just as the agile process often results in better software development, the same agile process applied to help material can be beneficial as well. To be agile, technical writers need to actively gather feedback about help material to improve it. Feedback from documentation doesn’t always need to be expressed as comments. Technical writers can gather feedback through metrics and other automated processes. Each help topic should contain tracking code to measure hits. Attending live training (or providing live training) and observing users can also be a means of gathering feedback. Technical writers need to be attuned to bug logging systems so they can connect with project team’s tracking of issues, and with the support center so they can monitor incident logs. Communication with product managers is also key to gathering verbal feedback. Where possible, technical writers should automate reports and other feedback on a regular basis and update the help accordingly.

Scope of information. Despite the attempt to provide business relevant content to every user, documentation does not need to provide instructions about everything. Too much information can make it difficult for users to find what they need. An over-abundance of information can dilute core task content and need-to-know topics. However, the technical writer does attempt to provide instructions for at least 80 percent of the typical user’s needs. Efforts to document the remaining 20 percent often fall prey to the law of diminishing returns; that is, for the effort required (tracking down hard-to-find solutions for unlikely scenarios), the payoff is little.

Help Plans and Processes

Prototype language. Technical writers should be involved in projects as soon as prototypes have been created. This early integration is necessary for technical writers to address interface language while there’s still time to make changes. Interface language is a component within the technical writer’s domain of expertise and should be treated as such. Technical writers should work closely with interaction designers in refining prototype language to avoid ambiguity — particularly in global contexts. Projects in which interaction designers are employed at the beginning, and technical writers at the end, often end up with broken interfaces.

Project plans. Technical writers should complete a project plan that provides project managers with a general estimate of the anticipated work and other details for the project. As an industry standard, it takes approximately four hours per application screen to create a help topic. This estimate of time for help topics only, and does not include time for creating videos, quick reference guides, or interface language. The project plan should also address the deliverables, expectations, risks, scope, timeline, and other details for the documentation. Failure to produce a project plan can result in a misalignment of expectations between project managers and writers.

Dual roles. Many times the technical writer becomes a subject matter expert on the application, having explored and examined it at length. The technical writer may become aware of bugs, usability issues, and support requests for an application. However, given the limited technical writing resources available, technical writers should only play these additional roles briefly. Technical writers may log or report bugs, but not necessarily flesh out the exact steps for reproducing bugs in every browser, nor conduct extensive usability testing, nor play support roles on the phone with end-users. If technical writers do play multiple roles on a project team, as is sometimes necessary in agile environments, project managers need to factor in this additional work into the project plan and estimated hours.

Approval processes. Before help materials can be considered complete, they must undergo review by several parties. The project manager should designate someone from the project team to review the accuracy of the help material. (Many times project managers themselves review this material, or assign quality assurance leads.) Other reviews may also be necessary if distributing the content externally. These reviews will add additional weeks into the completion of the help material. The reviews serve several purposes: to ensure consistency of style, to mitigate legal risks with content, and to provide another perspective on the coherence and accuracy of the content.

Tools and Technologies

Tools. Technical writing teams should use the same general set of tools so they can collaborate on files, share tips and how-to knowledge, and be interchangeable on projects. If one writer’s load becomes too heavy, he or she can re-allocate the load to other writers as long as the others can pick up and use the same tools. In most cases, use industry standards rather than open-source tools. Team members should also have the latest versions of each tool to facilitate collaboration.

Collaboration and content re-use. If external collaboration (such as with the community) is important on a project, a wiki works well. In fact, collaborating with large numbers of people in real-time is probably only feasible through a wiki, but the wiki doesn’t need to be the end product (the material can be exported). If only internal collaboration is important, other strategies may make more sense, such as a help authoring tool that stores content in a content management system. Ideally, if all internal collaborators can access and author from a central content management system, and render the outputs in a standard way without resorting to individual formatting, this can help with consistency and reduce the technical burden on content producers.

Corporate constraints. In a large organization, requiring every employee to standardize on the same toolset is difficult. Additionally, many times corporations limit certain tools and technologies from being installed. One must always work within a given environment while at the same time making strides to obtain approvals for more appropriate tools and technologies. Making appeals to industry standards can provide some leverage. Regardless, one can often accomplish the same results using many different tools and technologies.

Constant learning. Because technical writers often handle all aspects of content production, from creation to design to publishing to distribution in a variety of formats, including text, illustrations, video, and e-learning, the technical writer must constantly be engaged in learning tools and technologies. It’s not strategic to wait until the tool knowledge is required and a pressing deadline looms near. Rather the technical writer should schedule regular learning time, perhaps accessing sites like Lynda.com, into his or her daily schedule. When opportunities arise, the technical writer can leverage this knowledge to quickly design, illustrate, record, compile, call, style, or configure help content as needed. This learning is part of the technical writer’s job, and is an element that separates technical writing from many other types of writing.