Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Localizing a large online help system often represents the most expensive part of a localization project. However, when international customers or markets are a product’s lifelines, eliminating the online help translation is not an option, especially when customers have come to expect it. Managers of online help localization are left with a paradoxical mandate: Keep localizing, but quit spending (so much).
Dr. Bernadette Longo, Ph.D., uses the metaphor of devalued currency to trace some of the roots in technological history for technical writing's lack of intellectual and cultural capital. She ingeniously incorporates early threads of management and industrial technology, like the formation of the railroad, in an attempt to contextualize her research. Academics must view Longo's text, Spurious Coin, as just one branch of what must be a webbed tree of intersecting social attitudes towards knowledge definition and science. In understanding the gaps in Longo's narrative, people interested in technical writing might find her book to act as a launch pad for better defining the questions guiding their own research. In this review, I will focus on some of the important gaps I see in Longo's research methodology as she historically situates the emergence of engineering as a discipline and then as the determining factor in technical communication's subjugated position within the academy and industry.
We are currently in the second phase of development of a large Windows online help system. This paper reviews the major decisions we had to make during the first phase of the project, and lists some project evaluation results that have helped us plan for subsequent phases.
Developed by the Technical Information Division of Caterpillar Inc., the Service Information System (SIS) is a state of the art process using the latest in computer technology to electronically create, process and deliver technical service information to Caterpillar dealers worldwide. It utilizes authoring workstations and servers on a distributed network to create and store information elements (I/E's). The I/E's are written using Caterpillar Technical English (CTE) which allows for complete automatic language translation. I/E's are taken from the data base to make traditional publications as well as CD-ROM's. A personal computer is used to display information for shop and field servicemen and to perform interactive diagnostics.
This workshop provides hands-on experience in preparing and using online documentation as well as setting up and maintaining an online library.
Creating award-winning computer servicing documentation involves knowing something about customer service engineers, what content to provide, what kinds of art work best in different contexts, and differences in producing hard copy vs. online documentation. If you want to move from writing software or marketing documentation, find a good mentor to help you gain experience with these elements.
Want to provide your users with state-of-the art HTML Help but don't want to force them to install Internet Explorer (which is required to run compiled HTML Help files)? In this article we show you how to create context-sensitive Help that displays a topic from a .CHM file if IE is installed on the user's system, and displays the equivalent topic from a .HLP file if IE isn't installed.
The term 'easy to use' is typically used in connection with the user interface of software applications. However, the term can also be used to describe documentation, referring to techniques of organization, layout, or design that make information both easy to understand and easy to find. As the technology associated with documentation moves toward online and multimedia documentation, the concept of ease of use becomes even more important and relevant. In this paper, we address some of the differences between paper and online documentation that impact the development of easy-to-use online documentation, and outline some of the high-level, emerging issues to be aware of in the development of multimedia documentation.
If you have ever taken courses in technical writing, creating graphics was most likely addressed. Let's review the fundamentals and then delve deeper into creating tables in a technical document. Graphics, or visual aids, are usually divided into two broad categories: tables and figures. All tables are considered tables; all other visual aids are categorized as figures.
How do you create ERP documentation for your end users? One key is to map the five phases of the ERP documentation creation process to the phases of an ERP system implementation. Phase 1 is primarily for analysis, phase 2 is for the design process, and phase 3 consists of the actual building of the documentation. During phase 4, you should finalize all building and testing of the system. During phase 5, you should research end user trouble spots and continually improve the documentation in those areas.
By organizing information around the goals that users are trying to accomplish, you can provide task-based information that truly addresses user needs. This article walks through the steps for creating more useful information navigation by implementing information development best practices with examples in the Darwin Information Typing Architecture (DITA).
This is a presentation titled 'Creating Help in the Web 2.0 Age' that Neil Perlin gave to the Suncoast Chapter in Tampa, Florida in February 2007. Neil talks about what Web 2.0 is, and how help can be delivered on the fly according to specific user requests.
It is possible to create good, efficient, easy-to-maintain HTML Help systems - and it really isn't that difficult. The bad news is that if you're not sure exactly what settings need to be made, you will find creating modular HTML Help systems very frustrating. Read this article and avoid being frustrated.
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.
The proliferation of open systems and software that runs on multiple platforms is a challenge to those of us who are responsible for documenting these systems. This paper attempts to address the issues that arise when trying to create multiplatform information sets. Writing multiplatform documentation is a challenge not only for those responsible for documentation, but for those responsible for creating the software. You are starting with many pieces of a puzzle that you need to sort through and put together to create a usable information set.
With the explosion of online help authoring tools (primarily in the Windows® environment) companies are clamoring for the ability to produce online help on multiple platforms. This demonstration presents one solution to the problem of creating online help in a multiplatform environment. We will demonstrate the process of translating FrameMaker™ files from the Macintosh® to Windows NT®, and ultimately, to UNIX®.
An online tutorial or demo is a powerful way to pique interest and get users started on a new software program. Join a workshop that covers the how-to’s of creating your first project. (1) Make a plan. (2) Analyze audience needs and technical issues. (3) Form a team. (4) Write the script. (5) Design the interface. (6) Build it. (7) Test it.
Although most theorists agree that discourse creates meaning, they have not adequately described how this process emerges within the creation of procedural knowledge. This article explores how technical communicators in diverse settings based discourse decisions on their knowledge of (a) users, (b) organizational image and constraints, (c) software structure and features, and (d) genre conventions in order to create communication artifacts designed to help users develop procedural knowledge. The transformations in which they engaged indicated that these technical communicators were skilled in forming images in these four areas and then using these images as they created meaning in procedural discourse. In this process, they moved beyond merely translating or transmitting technical knowledge.
While Linux lacks standard Windows tools such as FrameMaker, RoboHelp, and WebWorks Publisher, it's still a viable environment for technical writers. Linux users can take advantage of a number of documentation tools, including both free or open source software (FOSS) and proprietary software. All of them give technical writers the ability to author and publish professional documentation.
When you are writing content in Flare, you may decide that you want to re-use some content that you previously added to another topic. We’ve discussed before how the best way to do this is to use a snippet, which essentially is a really long, formatted variable. To do this in Flare, you create a new snippet, then you locate the text you want to re-use, and copy the text out of that topic and paste it into the snippet. Then you replace the text in the original topic with the snippet, then insert the snippet into the new location.