Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Keeping track of a technical writing team’s time can be a tedious task, especially when that time has to be charged to various internal departments. Using Lotus Notes™ (Lotus Development Corporation and Iris Associates, Inc.), we developed a relational database to track this information. This database uses a single form for all documentation status inputs. Then it summarizes the data in a variety of view. Separate forms track SEI statistics and simplify department employee time administration.
As technical writers, we work more online than ever before. We are beginning to work with documentation in a new way, so that we can repurpose content and free it from the restrictions imposed by any particular delivery mechanism. We no longer solely create paper-publishable documents. We do not, as yet, have a good word for what we do; we do not have a single word or phrase that summarizes the effort or the deliverables. Nor can we use any single existing lexicon because the concepts are new. This difficulty is a natural consequence of the inter-networked world in which we work, where information is delivered multiple ways for diverse audiences. But let us look at the phrases currently growing in popular usage that refer to this effort.
Documentation for consumer products gets a bad rap. Often, it's deserved. But you can't paint all documentation with the same brush. This post looks at the good and the bad in consumer documentation, and at the elements which can make that documentation good.
This panel will discuss the development of documentation for global markets. Many practical tips will be offered for discussion.
We’ve all run in to situations where we have to document poor user interfaces. As much as we complain and suggest improvements, the project manager decides to go ahead with the interface as is because redesigning it is too costly. When I run into these situations, rather than insult the interface in straightforward talk in the documentation, I euphemize the language (against my better desires) in order to maintain the consistency of the company voice. It just doesn’t sound right to be so frank.
Everyone knows that documentation is a cost center, and that downsizing writers and moving documentation online save money. Unfortunately for 'everyone', it's trivial to demonstrate that documentation is actually a profit center--and we don't even have to wrassle with messy stuff like customer satisfaction to prove it.
In 2003, the Association to Advance Collegiate Schools of Business (AACSB) redefined their accreditation and reaffirmation standards to move from a traditional outcome-based system to a systematic process-based review. Documentation is required to assure student learning in several core areas, including communication. This paper outlines the data collection procedures and documentation methods used to document one university’s business communication learning assurances.
All documentation can stand some usability testing. We technical communicators like to claim that we’re user focused and user advocates. I like to believe that myself. However, sometimes we can be more like developers than we want to admit.
Producing documentation on CD-ROM can be extremely beneficial to users and can also save your company a lot of money over hard copy costs. To assure a successful roll-out of your CD product, it is critical to consider the involvement of key departments in your company as you plan the implementation in your user community. The two processes are closely related, and a well-integrated internal plan will help assure a successful introduction to your customers.
Basic checklist for assessing and improving the quality of technical documentation, especially software documentation such as user manuals, online help files, interactive demos and tutorials.
To implement any continuous improvement process, you have to measure your progress. This is where metrics come in. Have you been struggling to create a process for measuring your technical documentation? If so, this article provides the information you need to get started.
I’m curious about the value of adding all the font changes in user instructions: Is is valuable, or is it a distraction to users? What do you think? Access the poll and provide your answers. I promise to post the results.
Funny thing, documentation. Ought to be easy enough, surely? So why the disappointing results? What IS the elusive spark which distinguishes the professional author from others who put their hand to the pen (keyboard)?
For most of the technical writing community, task-based documentation has become the panacea for presentation of end-product document (in any of its myriad forms including traditional linear manuals and online help). We believe, however, that applying this method to a complex tool, (for example, a software tool without a Graphical User Interface), challenges the task-based approach.
The documentation strategy over the course of some development projects has, unfortunately, resembled a building with several add-ons rather than a single, unified structure—wings added, walls moved, different materials used. Where I live, no one builds like this, except in residential neighborhoods and on college campuses. This approach doesn’t exactly make for a consistent experience for users. It’s what I’d call documentation sprawl.
In the 1990s, product life cycles are short, technology is ever-advancing, work environments are fast-paced, and there is an ongoing agenda to cut costs. This environment requires documentation teams to accomplish more faster with fewer personnel resources These requirements have redefined the roles and responsibilities of technical writers and documentation team leaders. Leadership skills have become critical to the overall success of documentation teams Critical leadership skills include appropriately implementing situational leadership, working effectively with people who have diverse working and social styles, and participating in ongoing role negotiations.
Even though your customers may not read manuals, your tech support team probably does, which means someone is reading the manuals and using them to help others. But if your users find it easier to call someone, wait on hold for an agent, and then ask the agent a question rather than find the answer in the help, maybe your help materials aren’t very usable. Maybe increasing the usability of your company’s documentation could alleviate the need users feel to seek answers from another source.
what can you do if you don’t have a technical writer or the standard tools? You just might have to go quick and dirty. Quick and dirty documentation is a band aid, no doubt about it. But it’s better than nothing. This article presents some thoughts about ways to deliver documentation quickly and cheaply.
Is providing Linux documentation an insurmountable task? I'm starting to think so. The major technical book publishers have dropped their efforts to recruit authors and publish sysadmin books. Instead, they have started focusing most of their attention on programming. Who can blame them.