Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
A lightweight markup language uses syntax that is similar to wiki syntax -- keyboard characters are used to define formatting. This blog post argues that if your documentation needs are simple, and you have a low or non-existent budget, then a lightweight markup language might be worth investigating.
We have two distinct sets of users; internal product consultants and end users. Prior to using RoboHelp Server we had little way of identifying who was looking at our documentation, when they were looking at it, or how often. That has now changed.
For simple, commonly known actions in a closed environment, you probably can design your way to a “no user documentation” approach. Good design can also lead to less documentation. However, customers may expect to do more than that with a product and, in those situations, documentation can play a key role in meeting those expectations.
While putting together a good tutorial movie for your blog or for an article you’re writing requires some thought and preparation, and would benefit from extra time spent on post-processing, the good news is that capturing screen shots and screen movies can be done inexpensively on a Mac. Although I take a glance at the wider context of preparing an entire tutorial and give you some tips along the way, my focus here is on the low-cost software you can use.
In July, in a sharp break from tradition, the Army began encouraging its personnel — from the privates to the generals — to go online and collaboratively rewrite seven of the field manuals that give instructions on all aspects of Army life. The program uses the same software behind the online encyclopedia Wikipedia and could potentially lead to hundreds of Army guides being “wikified.” The goal, say the officers behind the effort, is to tap more experience and advice from battle-tested soldiers rather than relying on the specialists within the Army’s array of colleges and research centers who have traditionally written the manuals.
Braun Corporation's home-grown documentation processes served the organization well for its first 50 years as it grew from a local to a nationally-competitive producer of mobility and accessibility products. Now poised to become a global leader in its field, this corporation found its efforts hampered by ineffective and outdated documentation practices, which were hurting the company's competitive advantage. This article describes Braun Corporation's curious mixture of global reach and local isolation. By bringing in a technical communicator with expertise in user-centered design, Braun has begun reforming its formerly exhaustive documentation and communication practices. While technical communicators have incorporated a variety of strategies to develop user-centered and task-based documentation, less attention has been placed on changing the cultures of these organizations. The case presented here represents a shift from establishing documentation procedures to critically assessing and reforming existing procedures for the global workplace, describing the shift from ineffective and exhaustive processes to effective processes with defined goals and measurable outcomes. The article concludes with an inventory for determining whether other organizations are over-documenting processes and products, and offers suggestions for creating better documentation procedures.
The non-writer who takes over the documentation can act like a bull in a China closet, copying and pasting from Word, mixing styles, not understanding the setup, basically wrecking the consistency, the bullet levels, the formatting. If you see the documentation later and find that the client has added steps without numbers, included text that breaks every rule in the style guide, won’t that be unnerving? Yes, it will make you want to jump out the window.
Charles Cantrell, an Information Engineer, describes Ontario Systems' process for delivering dynamically assembled and populated documentation for Artiva, its 'highly customizable' accounts receivable management application.
In looking at my documentation, I found a couple of inaccuracies, and it’s possible that they were the direct cause of the data problem we ended up with. I haven’t verified this yet because at this point, it looks like it hardly matters (as long as I correct the inaccuracies). If my documentation led to the problem, it has led us to analyze a bigger problem that’s really at the heart of our customer’s difficulty. The discussion has been about what needs to happen in our system vs. what is actually happening. We think the programming and the data model have fallen short in some ways; fortunately, the wiring can probably be fixed with relatively little pain. It’s a matter of making sure we know what the customer wants to happen so it will be programmed the right way.
Triangle is a systems integrator in the UK with about 150 employees. It extended the functionality of the InfoGenesis point of sale software onto hand-held terminals. To turn this into a commercial off-the-shelf product, Triangle needed clear documentation for resellers and for staff managers at customer sites. Triangle lacked the expertise needed to produce effective documentation, so it outsourced the documentation development. The new documentation enables Triangle to roll out the software internationally using resellers, and keeps Triangle's support costs to a minimum.
Context-sensitive help systems often need redundant placement of information. This ensures that the information is seen by visitors who enter and move unpredictably through the system. Redundant placements take the form of descriptions, explanations, warnings, and the like that amplify other subjects. In software documentation, for example, some candidate subjects include the purposes of screens and tabs, the effects of selected options and significant functions such as Delete, and reminders of required access permissions and prerequisite steps or conditions. You can save development time and promote consistency by cataloging information so that it can be inserted wherever needed using your authoring software's copy and paste functions.
Safety and warning notices form the most important elements of user information wherever safety and [product liability are concerned. A carefully thought out and systematic process is required in developing safety-relevant information, in order to increase the completeness and comprehensibility of product safety. This will also disarm any suspicion of gross negligence in internal documentation in case of missing safety notices and it will ensure traceability.
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 John Gale 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.
There are many significant benefits to releasing documentation on CD ROM rather than on hardcopy including cost savings, storage capacity, and the ability to implement search and retrieval functionality. To determine whether or not you should go to CD ROM, it is advisable to survey your users and to get approval from the folks in "corporate." Once you decide to pursue CD ROM, you need to determine the platform requirements and feature set of the search and retrieval software. You will then be able to choose from a variety of products, and ask the selected vendor to produce a prototype for you.
Using a modular process has proven highly effective in developing both on-line and printed documentation. This paper identifies module types and structures, discusses technical, psychological, and management hurdles, and demonstrates how this process can improve consistency and quality. In addition it discusses tools and resources, preliminary planning, preparation of personnel, and (briefly) tracking results.
There are at least two important issues that are closely related to the open-source software support questions we raised in part 1 of this look at open-source practicalities: documenting the software and training people to use it. With a traditional, commercially licensed product, documentation is as simple as obtaining a hard copy, a CD or going online to get all the details needed from the software's developer. Or, if something is missing, using support from the vendor to get questions and issues resolved.
The Information Products (IP) group at Sun Microsystems Computer Company (SMCC) recently revamped thew documentation strategy for computer server products. While creating the new model, we realized that our goal for more streamlined documentation would be more attainable if we did not restrict ourselves. Instead of starting with an old, key factor assumption — that manuals should be written with 'Who is the customer?' in mind — we addressed questions such as 'What tasks are required during installation and maintenance?' and 'Who perform these tasks?' By replacing some old ideas with fresh ones, we developed a new documentation strategy.
There's a shift happening in the way in which documentation is produced. We’ve all seen the beginning of it: the growing volume of what’s called (among other things) user generated or crowdsourced documentation. That trend is growing. And while a number of people in our profession are still resistant to the idea, it’s only a matter of time before users are our main partners in creating documentation.
When the subjects of usability and user friendliness in relation to documentation are broached, writing isn’t often the first thing that comes to mind. But it should be.
Often conflicting pressures to produce communications that better fit customer demands as well as stay within tightening constraints on budgets and schedules are leading many technical communications organizations to a topic-based approach to authoring. In fact, 58% of participants in Aberdeen Group's October 2008 DITA and the Technical Communicator’s Transformation study report that they currently follow author content in a topic-based manner, with a vast majority of those remaining planning to implement one in the future. A topic-based approach promotes greater content reuse and is seeing a considerable impact on the authoring efficiency of technical communications projects today. The benefits of topic-based authoring can be compelling, with findings from the The Technical Communicator’s Transformation study indicating that when pursued the right way, topic-based authoring can have a broad range of benefits, enabling an organization to meet authoring and localization cost targets as well as documentation quality expectations, among others. However, as the adoption of this approach spreads, the advantages seen by today's leading organizations will flatten out. This Sector Insight provides a guide for current adoption of topic-based authoring and those still considering it; outlining the changes that are expected to take place in as topic-based authoring goes mainstream.
Einfache Checkliste zur Beurteilung und Verbesserung der Qualität Technischer Dokumentation, insbes. Technischer Dokumentation für Software (Software-Dokumentation) wie Handbücher, Online-Hilfen sowie interaktiver Demos und Tutorials.