Here is an example of how Search could fail. Your company Help System, a Policies guide, includes a topic concerned with contraband substances in the office. The word contraband is contained within the topic so the word will be found if users search for that specific term. However, a user who is curious about contraband substances might elect to search the Help System using another word, such as illicit. Because the word illicit isn't in the Help System, the Search will fail. There are a couple of ways to fix the problem. One way would be to add Search terms to the properties of individual topics. Another way, which I'll cover here, is to use RoboHelp's Advanced Settings for Localization to create a synonym (illicit) for contraband.
Madcap Flare is one of the most powerful online help authoring tools on the market today. In this podcast, Paul Pehrson, MVP in the Madcap Software forums, talks about Madcap Flare in depth.
Facing the challenges involved in developing documentation for component-based software (for example, object-oriented technology, intelligent agents, and distributed computing) requires a documentation strategy based on the same processes and methodologies used by such technologies. These strategies need to be adapted to meet documentation, rather than coding needs. Developing this strategy now, as component-based technology is still maturing, will help technical communicators keep pace.
Audacity is a free cross platform multi track audio editing program from Sourceforge.net. It will let you record, edit, and mix an unlimited number of tracks. Audacity runs on Windows (98 through XP), Mac OS X, and Linux.
WebWorks AutoMap is an extremely useful tool for performing unattended documentation builds. Out of the box, AutoMap can generate reasonable documents. By adding the power of scripting, the results can be amazing.
Having introduced the concept of high definition PDF's output straight from Flare's source files with minimal post-production, we can now start to dig into the technologies that are used to produce it.
Help authoring tools (HATs) are specialized editors and converters to create online technical documentation. Today, many help authoring tools also provide features for single source publishing, which means that you can generate several output formats and versions from one shared text source. While most tools manage to produce different online formats like browser-based help and compiled help very well, only few tools can also produce printed user manuals (or PDF) of professional quality. Big differences also exist between the tools when it comes to translating your projects into foreign languages.
Checklist of key criteria for selecting a tool to take screen captures (screenshots / screen dumps). Screen captures are used within all forms of software documentation, such as user manuals, online help files, interactive demos and tutorials, but also for web sites and brochures.
Checklist of key criteria for selecting a tool to create interactive software demos (so-called screencasts). Software demos are not only used on web sites but increasingly also as standalone tutorials or embedded within online help files and other sorts of software documentation.
Learning the correct steps to install or remove a computer component, such as a memory module, can involve, at best, hands-on instruction or, at worst, only written instructions. To increase the likelihood that customers and service personnel will be able to perform correctly the hardware service procedure for each fieldreplaceable component, Sun MicrosystemsTM now ships high-quality multimedia of removal and replacement procedures, called ShowMeTM How, on CD with each UltraTM Workstation and Enterprise Workgroup Server.
If you are like most technical writers, your procedures have automatically numbered steps (whether in tables or text), Microsoft Word provides two relatively simple ways for you to cross-reference a step number.
Kein Wunder müssen Technischen Redakteure die ganze Zeit Druckdaten aufbereiten, wenn jede Druckerei ein anderes Datenformat verlangt. Eine Lösung musste her. Ein Standard. Und so ist auch PDF/X-3 ein Thema in der Technischen Dokumentation.
Sometimes our developers are just a bit too eager. It doesn’t happen that often but when it does, it takes us Technical Writers by surprise. One such occasion happened today when the first build was created for the next release of one of our applications. No real issue there, but when they came to us half an hour after the build process completed to say the help didn’t look right, we went to investigate.
The challenges of documenting entertainment software are in many ways the challenges of all technical communicators. We strive to make the interface intuitive and the documentation interesting and easy-to-read. Although the nature of the world of entertainment may suggest that our task is simple, the breadth of our audience and the depth of our goals makes it more sophisticated than it looks. We must be as imaginative as our users, recognize the emerging dimensions of multimedia, and create with the constraints of low retail costs, small teams, and fast-paced deadlines.
This question was raised on a programmer's group recently and I was intrigued. The programmer's point was that with many web applications these days there is no print documentation distributed to end users, and even if it existed, many users won't read it although this makes me wonder who's buying all those how-to books I see in the bookstore. The programmer suggested that applications should be designed without documentation and wondered about the impact that would have on design.
Software documentation can be difficult to review, so it helps to have some editing guidelines to keep you focused. Let's face it; software documentation isn't exactly exciting reading material. But you should be able to complete the job in a productive manner if you keep your coffee cup full and follow the editing guidelines below.
Whether software documentation is designed for a company’s internal users or for a variety of end customers, one thing is for certain: Documentation that is well written, well structured, easily accessible, and thoroughly compliments the software it supports can play a significant role in a product’s overall success. And it doesn’t matter if the documentation stands alone or it is integrated with the product. As long as it is properly planned, developed, and configured, success is eminent.
Often when we start a new job, or are dropped into an existing software documentation project at our current job, getting up to speed is overwhelming. This article suggests steps to quickly assess the situation, develop a plan, and begin writing.
This study investigates whether Iconic Linkage--the use of the identical wording to present the same information recurring in a text--can improve the usability of user guides. Iconic Linkage is a writing strategy that potentially allows users to work more quickly and effectively and which promotes better retention of information. The usefulness of Iconic Linkage was tested in a laboratory-based usability study that combined: 1) objective task-based evaluation; and 2) users' subjective evaluations of a software program used in recording parliamentary debates. A post-test survey designed to test subjects' retention of information contained in the user guides was also administered. The study shows that Iconic Linkage significantly improved usability of the user guide: in all tasks, subjects worked more effectively and made fewer mistakes; while in the three timed tasks, subjects completed the tasks much more quickly. Subjects also gave higher ratings for the software and their retention of information was noticeably improved.
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.
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.
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.