Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
The Help platform for Microsoft Windows is changing once again. Since 1995, Microsoft HTML Help has been the standard for Help systems for Windows applications, but the release of the next generation Windows operating system in 2005 will see a brand new XML-based Help platform. It is currently known as Help.Longhorn, or "Longhorn" Help, or sometimes as Help3 or TrésHelp.
This is a very simple example of integrating a J2SE application with the Apple Help Viewer application. This sample code has been updated to include a project that produces a universal binary. No code changes were required for it to run correctly on Intel-based Macintosh computers.
In the PC products market, customers insist on excellent support at rock-bottom prices. The traditional model of customer support, having a phone technician answer customer questions, is becoming too expensive.
We all are familiar with Jakob Nielsen's heuristics for evaluating the usability of interfaces. When I was conducting a study on documentation usability, I started wondering if there existed a similar set of heuristics for evaluating the usability of documentation. The natural place to pose such a question was the STC Usability SIG mailing list. The response was that there was no heuristics set available although someone had tried to open the discussion in the mailing list some time ago. An answer, which led to the list of heuristics presented below, was something along the line 'Well, now that you asked, why don't you put the heuristics together' and so I did.
When companies decide whether or not to adopt a CMS or continue using a HAT, there are many factors to consider. Perlin outlines elements of both CMSs and HATs that could help you determine which is best for your organization.
The first impulse of many documenters is to turn our work over to editors and graphic designers, or to form committees and develop style guidelines. All of these measures are useful, but none can assure us of quality when there are basic problems with the way we go about producing documentation.
Writing software manuals is boring, isn't it? We often think, "My software is easy to use. The user interface is intuitive. Why should I waste so much time writing documentation which nobody will read anyway?" Sometimes it's true. I've never read the WinZip or Internet Explorer manuals. Everything seems clear enough without further explanation. Nevertheless, even if your manual isn't being helpful to your software users, it may be helpful to you. Publish your manual online and turn its hidden power into a real benefit for your business.
This paper discusses how information designers, especially those who are members of multidisciplinary teams following a user-centered design (UCD) approach to designing a product, can define a highlevel design for a product’s information. It will discuss what data designers need before they can make design decisions and what activities they can perform to define a high-level design. A partial list of new skills that technical communicators need for UCD is also included.
The writers at Software Publishing Corporation faced the challenge of reducing the page count of their manuals by more than 50%—without sacrificing quality, extending the schedule, or starting from scratch! They found that approaching this daunting task from several different directions at the same time proved to be the most effective. While the following tips apply primarily to DOS and Windows software manuals, the tips are a good starting point for streamlining any documentation set. The benefits include cutting dollars from the per unit cost of goods and promoting greater customer acceptance of documentation as a learning tool.
Of all the visual cues in your help interface, color is one of the strongest. Users will recognize and react to the color of each element in your help window before reading a single word of text. Color allows users to determine the purpose of each element on the computer screen. When designing the visual aspect of your help content (via CSS and so on), as well as the help interface itself, be sure to use the same color for objects that share a purpose.
Most people involved with authoring and reviewing process do not have good markers to inform them of the overall communication quality of a document. So without good markers they are left to utilize really poor markers to help them measure document quality.
After some deliberation, the thought came to me to try two levels of dropdown hotspots. This screen is divided in sections, so I rearranged the information so that I had a hotspot corresponding to each section. Each hotspot would expose another set of hotspots and any other information about that section in general. This would allow the user to navigate directly to what they want rather than having to scan and scroll through a bunch of text.
Embedded user assistance is only part of a complete documentation plan. It does not replace the need for other types of content. For example, embedded user assistance is not a good delivery mechanism for comprehensive concepts and detailed discussions of a topic with strategy and best practice guidelines. However, with a strong design, embedded user assistance can support the immediate needs of the user and provide a valuable, contextual link that steers the user into the other parts of the documentation as needed.
Last week Google released Google Voice, a service that allows you to integrate all your phones into one number and includes a host of features, including voice mail, recording, conference calling, and other services. To help users get started, Google Voice has a list of 20 short videos. Only the overview video contains animation. It’s certainly the video they’ve put the most work into, and it also functions as marketing collateral.
Why would people be nine times more willing to go to a website than an online help system? Since this may have been explained in the webinar but all I have regarding it is Sarah’s tweet, my initial guess is that people tend to think a help system is static and easily outdated (they don’t know about the Agile technical writer?), while a website is fresh and frequently updated. Whether those things are actually true isn’t as important as the fact that the audience perceives them as being true. This led me to thinking that all is not lost for help authoring tools, though. I’m sure with some effort, I could make an online help system look like a website.
Every help authoring tool seems to have a different approach to presenting search results. Offerings range from ranked results to alphabetical lists, with additional features thrown in such as the inclusion of chunks of topic text with highlighted search keywords. Each method of presenting search results offers different benefits to users. Since help tools offer mixed approaches, I feel perfectly comfortable throwing my own opinions into the mix.
Creating video tutorials is no trivial task. When you sit down to create 20+ video tutorials for a project, you’re faced with dozens of questions. What screen size should the videos be, what recording tool should you use, what microphone is best, how long should the videos be, what file size is acceptable? Should you use voice or captions? Where will you create the recording? You can create video tutorials using dozens of different methods. There are no official steps to create videos, because situations and audiences vary so widely.
Over the last few months, I’ve been working with a number of mobile devices. Not professionally, but on my own time with my own devices or devices that friends have graciously loaned me. While having fun and experiencing the occasional frustration or moments of head scratching, I kept asking myself how much documentation does this thing really need?
There are a number of well known factors that impact the effectiveness of documentation, both as an aid to learning and as a guide to getting the job done. An approach to documentation known as minimalist has been around for many years, but remains little know outside specialist interest groups. The approach produces clean easy to read documentation. Manuals and guides produced using the approach have a much higher probability of being useful and therefore of being used.