Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Effective technical manuals and training meet the needs of the customer. No one will argue with that statement. But the trick is to identify the needs of the customer. This paper describes one method to focus product information development on the customer: the needs analysis survey. This methodology that is common in course development and training identifies the tasks customers perform. It also allows course developers and technical communicators to collaborate on an area that they both understand.
A voice over is a voice narration from a performer whom you can’t see, who reads a script in an engaging way according to the context of the script. For example, many commercials employ voice overs from professionals. The difference between voice-over performers and announcers, Scott says, is that voice-over performers get outside of themselves, whereas announcers merely read a script.
Finding information in documentation is easy. Or is it? This blog post argues that there's no universal solution, and that each document and each delivery method offers challenges and requires a slightly different solution.
The concept of the “paperless oflce” has become popular with executives who want to reduce costs and users who, often with good reason, refuse to open a manual. Technical communicators, who often understand the practical flaws behind this concept, must be prepared to make smart decisions about what information to present in manuals and what to present online. They must also justljj to management their decisions either to resist moving everything online or tofkd creative ways to do so without forgetting about the needs of the user.
I conducted some context-sensitive online help usability testing with four users of a Web application. This post discusses the results (without getting overly academic in tone, I hope).
The Firefox Support Knowledge Base is a collaborative work of dozens of contributors, the Support Forum is bustling with people answering questions, and Live Chat is manned by dedicated team of community members.
You've never met them before. To you, they may represent the unknown and the strange. They view things differently, and their ways may seem almost alien. Yet you are supposed to serve their needs. They are your customers. Isn't it time you made first contact? In this paper, we share lessons learned and invite you to being your own voyage of discovery.
Customer support costs account for as much as 60 percent of a high-tech company’s total costs. Documentation is the first line of support for most customers, and customers usually use documentation to find the answer to a problem they’re having. The inevitable result of poor or nonexistent documentation is that more people try calling the customer support lines for help.
Social Media experts, such as David Armano, of Dachis Corp, are proposing new business measures for assessing the effectiveness of social media marketing. Armano is proposing five key measurement factors. So can technical documentation be “re-framed” to meet these criteria? If so, will its value to the business become clearer?
Good API documentation can have a tremendous impact on whether a software platform is adopted. However, too often API documentation ends up being confusing and hard to follow, which results in developers choosing another way to accomplish their goals. This article describes five common mistakes that are made in creating API documentation and describes solutions to avoiding those mistakes. Following good API documentation practices can provide developers with the content that they need to be able to take full advantage of a software platform's capabilities.
With all the screencasting going on in the blogosphere lately, what with tutorials running rampant across all different video sharing websites…I thought I’d share a few screencasting tools for those of you looking for a free alternative to some of those higher priced utilities. This review covers both PC and Mac utilities, and not wanting to leave anyone out…one for those running Java.
Industry best practices are business processes that assist companies, government agencies, and non-profit organizations in maintaining the highest level of quality in the products or services that they are offering. A lot of it might seem like common sense, but if you saw some of the things that I have seen in the different projects I’ve been on, you’d realize that sometimes you can just rely on that. Here are five industry best practices that you should adopt, regardless of the type of organization that you are running.
Being asked to take the reins of a brand new documentation department is a challenge that many professional technical writers relish, even though the training and development activities they participated in may never have prepared them for such a rewarding challenge. This article looks at forming a new documentation department and determining what's needed, when it's needed and what resources are available to help the new department carry out its mission.
You're the manager of your company’s emerging documentation department -- and your work has just begun. To create effective documentation for your customers, you not only have to build a sound team, but also build working relationships with all other departments in your company.
Recently, I’ve been exploring the need for writing procedures in real-time, focusing on Twitter in particular. This is the fourth post in the series. In my last post, I was asked by Larry Kunz in a comment for thoughts on situations in which one might write procedures in Twitter. Five come to mind; I’ve described them below.
Sometimes, the Agile software development methodology seems like it could be renamed the “Fly by the Seat of Your Pants” methodology. But really, it means that you need a somewhat different set of project management skills for your documentation. I could certainly improve in these skills, but here are a few I rely on in an Agile environment.
For decades, journalists have used a proven approach called the 'Five W's' to answer the questions that the readers of newspaper articles most commonly want writers to answer. The questions are sufficiently useful that they can easily be applied outside newspaper writing, and I've already written about this in the context of audience analysis (Hart 1996). In this article, I'll show you how you can use these questions to develop more useful online help. Each of the five W's is a simple question that starts with the letter W: Why, Who, What, Where, and When. Some authorities add a sixth question, 'How,' to this list, but 'how to' information generally fits under what, where, or when, depending on the nature of the information. Users of online help can benefit greatly from the proven journalistic approach if we can answer these same five questions for each help topic that we create. In the remainder of this article, I'll provide an example of a failure to ask these questions, show how asking these five questions could have prevented this failure, and provide examples of typical questions we should be asking. Please note that, although I've presented these five questions in an order that seems logical to me, in practice the approach becomes iterative: It doesn't much matter where you begin, since answering one question often reveals important aspects of the other questions that you'd not yet considered.
“Congratulations on purchasing your iPod shuffle.” Have you seen this congratulations sentence before? I see this same pattern of congratulations on almost every manual for products I buy. Could no one think of any other way to kick off the start of a relationship between a product and user? Take the coolest kind of product, an iPod that goes underwater, and then drown the user guide with a cliche.
Flare current provides the majority of HTMLHelp settings, and does this in a much more flexible way that HTMLHelp workshop does. Particularly useful are the WYSIWYG help window size and potitioning. However, there are some advanced HTMLHelp settings (such as advanced help, or remembering the users last help settings) that are not currently available.
If you're moving to Flare from another help authoring tool, you'll find that Flare's stylesheet editor is very powerful but different than other stylesheet editors that you may have used. And if Flare is your first help authoring tool, you may find the stylesheet editor overpowering at first. To help you get over that initial hump, Hyper/Word Services offers a stylesheet for Flare that will help you learn to use the stylesheet editor, and that may apply to actual projects.
As the web transitions from a relatively static, information-oriented environment to a highly interactive, task-oriented environment, web developers must provide on-demand user assistance to ensure the usability of their applications.
There’s a lot of tool fetishism in the documentation world. We all succumb to it in one way or another — I used to think it was FrameMaker or DocBook, or nothing. Ah, the folly of youth. But that attitude severely limits you as a professional. For a consultant or freelancer, it’s only a few steps away from suicide.
Documentation is one area in which free/libre/open source software (FLOSS) is weakest. A project called FLOSS Manuals is trying to remedy this situation. The idea behind project is to create quality, free documentation for free software.