Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Documentation has to have an aesthetic strategy. Documentation has to be consumable. It has to be friendly, not just in the way it’s written but in the way it presents itself. It should be easy to read, it should look attractive, and it should look like something you want to engage with.
Flossmanuals.net is a new wiki help authoring/publishing tool hybrid that, as far as I know, is completely unique. The site is more than a wiki. It allows groups of authors to create specific chapters independently. You can then remix the chapters into any arrangement and selection you want through a drag-and-drop interface.
Some companies and upper management, and even some documentation managers and writers, seem to agree. After all, in today's world of desktop publishing, writers are also typesetters and illustrators -- why not let them be editors as well? They know English. So why not save money, terminate the editors, and let peer editing begin? Or if we do keep some editors, let them be the designers, illustrators, and typesetters. As for language? Forget it! The readers will understand. Besides, who reads documentation anyway?
While I'm a firm believer in the primacy of content over appearance, aesthetics are definitely a part of drawing people into documentation and engaging them. There's nothing wrong with making online assistance or a printed manual attractive. It doesn't need to be a beautifully-designed work of art, but it should be something a little more than blocks of black text on a white page.
"FOSS programming is fun -- it's rewarding," enthused Linux Rants blogger Mike Stone. "If you create something great, people recognize your name, your brilliance." Documentation, on the other hand, "is none of that. When you're doing a project for fun, it's hard to be motivated to do something that's not fun or rewarding." As a result, "FOSS documentation will always lag behind FOSS software."
Honda of America's adoption of a structured analysis and design (SA&D) methodology for software development has allowed the Technical Publications Group to improve project planning. Documentation is now integrated into the system development methodology, and writers receive deliverables such as design documents and approved project plans earlier in the development process. With the addition of a project management tool that provides a central repository of project data, the group now creates more accurate preliminary and detailed documentation project plans. Results include an increase in documentation delivered at system implementation, and improved allocation of resources.
This presentation addresses designers and documenters who develop technologies for human use. The content is based on an intensive 42-hour training package, developed by Communications and Training Inc. Course content and duration can be modified to meet individual requirements. One day interactive workshops are also available.
The increasing number of languages that companies need to translate into requires careful planning when preparing translation projects. Thus, choosing appropriate tools, finding qualified project teams, and applying suitable concepts to avoid additional work become crucial tasks for the project manager. If all these issues are considered beforehand, a perfect balance can be achieved within the magic triangle of time, cost and quality.
A few years ago, the NeXT user publications group was handed a charter to create casual books with personality. We were also told to condense the user documentation for an entire operating system and several bundled applications into 300 pages. And of course we had the top priority of creating accurate, complete, and easy-to-use documentation. To our delight, these goals ended up being mutually compatible. The keys? Task orientation, flat hierarchy, carefully crafted page design, illustration, and a casual, intelligent tone. We also broke some 'rules'! (Caution: Some of the following material may seem radical to seasoned traditionalists.)
Our plight as users of process information is much like that of the users of the information for our software products. Like them, we want to do useful work and get appropriate assistance when we need it. Instead of just reading about a task such as writing an information plan, we want the templates and samples to use when writing the plan. Just-in-time assistance, experience captured in a useful form, would suit us just fine. This paper, by the designers and developers of a system that supports the work and processes of a user technology organization, presents the information design issues that we encountered and the design of the system that we created.
This demonstration introduces the concept of an Electronic Performance Support System (EPSS), an online end-user support system that provides whatever is necessary to generate performance and learning at the moment of need. The speaker will step through a five-level analysis of the design and delivery components of an EPSS and demonstrate how to design and position online documents for inclusion in an EPSS.
Online help systems have evolved over the past twenty years to meet the needs of our users. Designers must consider the content, format, presentation, navigation, and access methods of online help systems. A series of design checklists based on the past 20 years of research are presented in this paper, which summarizes a journal article currently being considered for publication. The latest trend in online help system design is embedded user assistance, which includes integrating information into the interface and including an embedded help pane within that interface to display a context-sensitive online help system.
For usability’s sake, the development group at Strohl Systems created a navigational coach that embedded user assistance within the company's flagship product. Now we're redesigning the product and building it around the user assistance.
A panel of industry experts provides an overview of the CD-ROM publishing process—and its business issues–for technical communicators who are responsible for implementing CD-ROM publishing in their organizations. The panelists will discuss how to gain the benefits of reduced manufacturing warehousing and distribution costs, without degrading documentation quality.
This presentation will describe an area of documentation that is often overlooked--that which covers the process between the customer purchasing a computer system or upgraded software and the customer becoming productive using that system or software. This information includes all that needs to be planned and accomplished to get new software up, running, and integrated with existing software. Unisys Corporation fills this gap with what we call 'Release Documentation.' This presentation describes the who, what, where, when, and how of that process.
Marketing documentation entices clients to buy your products. Technical documentation tells clients how to use your products.
Interested in making the transition from software documentation to e-learning? Read about some steps that will help you ease the switch and make the most of your new opportunity.
In response to their institution's need to explain its research to the public, a group of technical writers from Los Alamos National Laboratory is investigating methods to help writers make the leap from technical writing to science communication--the art of communicating science to nontechnical audiences. Through individual study and networking, members of the group are collecting resources that illuminate the techniques and complexities of science communication. From this foundation, they are preparing an extensive, annotated bibliography and assembling training materials so that they can become a resource for other writers shifting from technical to science communication.
Technical communicators have become increasingly interested in how to 'open up' the documentation process - to encourage workers to participate in developing documentation that closely fits their needs. This goal has led technical communicators to engage in usability testing, user-centered design approaches, and, more recently, open source documentation. Although these approaches have all had some success, there are other ways to encourage the participatory citizenship that is implied in these approaches. One way is through an open systems approach in which workers can consensually modify a given system and add their own contributions to the system.
The RoboHelp help authoring tool is now entering its thirteenth year of existence. That's a remarkably long existence for any software title. In that time period, we have seen an amazing expansion of the software industry throughout the 1990s and an equally amazing retraction due to the bursting of the Internet bubble. Making its start in the tiny offices of Blue Sky Software in LaJolla, California, RoboHelp grew into an extremely profitable product. It is also a market leader—having capturing some two-thirds of all Help authoring tool sales. During the Internet bubble years the company changed its name to eHelp, but RoboHelp continued to be its flagship profit center. In 2003, eHelp (and RoboHelp) were acquired by one of the leading providers of web tools—Macromedia. Now it appears that the end may be approaching for RoboHelp.
The need for TCs with traditional writing skills will remain fairly stable, but the need for TCs in total will grow. The new technical communicators will come from the world of game design, where they know all about 3D-vector animation, and they will come from the world of TV and video production.
With online help rapidly becoming the central piece in the documentation set, software companies might consider two different directions in their documentation planning. The first is to think of the user’s guide as a high-quality supplement to help. The second is to think of the user's guide as a transitional piece that will adequately support users while they make the transition to a largely online documentation set. Each of these directions carries different implications for the design of the user’s guide.
Visual information has always been tremendously useful for documentation. The assembly instructions for a piece of furniture from IKEA, for example, are almost entirely graphic so as to minimize translation costs. But graphics also offer challenges when used in online outputs. Should we show graphics in the online help or documentation? Should we show them automatically or link to the graphics and leave it to the viewers to click on the links? What graphic file format is best? How big should the graphics be? And so on.
Men and women have different approaches to dealing with technology problems, according to a gadget helpline. The service found that 64% of its male callers and 24% of its female callers had not read the instruction manual before ringing up.