Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Many organizations produce in-house tools or modify commercially-available tools for their own use. These tools should get documented so they are of use to others in the organization. If this documentation is not created or is poorly written, it costs you twice.
The biggest concern in software development environments is the retention of programmers. What they are really concerned about is the knowledge drain. These organizations know they need to capture this knowledge, but they do not want to do it themselves. They are turning to the writers who have always written the user manuals. These writers, most having no systems or programming background, must develop internal documentation for use in a programming maintenance environment. They do not know where to begin. This paper outlines a methodology for developing systems and programming documentation for programmers in a maintenance environment.
Although there will always be a need for people to explain technical material non-technical people, Ellis Pratt said, others may be doing it instead, through the formats users prefer. To survive, technical writers may need to morph into content strategists, managing the information in a systematic way rather than merely creating it.
In Conversation and Community: The Social Web for Documentation, Anne Gentle offers tips for mashing up user-generated content with user assistance, including ways to bring Web 2.0 to user assistance, and vice-versa.
Capturing the essence of a topic is the heart and soul of good writing and editing. If you cannot tell what the main idea is, you cannot write it either. And if you cannot write it, how would you expect your readers to get it? So it all starts with you. Thankfully, it is not mysterious process. Here are two techniques that you can use to weed out the irrelevant details from your core idea.
If the success of an open source project can be measured by the number of third-party books about it, then OpenOffice.org is thriving. Not only is OpenOffice.org represented by a dozen books and pieces of training material on Amazon.com, but interest in OpenOffice.org is widespread enough that each of the books is geared to a slightly different audience. This article gives an overview of four of the current OpenOffice.org books, ending with a suggestion of which to buy for your own needs.
Technical writing has a number of moral and ethical standards that a professional technical writer needs to comply with. Violate them at your own peril, by risking the sudden demise of your career. Here are some of these issues.
If you've been a technical writer for long, chances are you've had to convince someone of the importance of documentation. It just comes with the territory. People often don't see the value of writing technical manuals. So how do you convince them?
In this post, I want to explore Help APIs, which is actually something in part enabled by static site generators. To put things in context, the web is sort of a giant API. Each browser functions as a client that accesses various resources from servers.
In this tutorial we will learn how to create flexible image grid layouts in Adobe InDesign. We will use several useful image frame techniques like Fill frame options, Auto-Fill, Gap Tool, Rounded Corners, etc.
In this podcast, Joe Sokohl explains how to create user-centered documentation by contacting, observing, and interviewing users to gather information about what types of information they use and the help deliverables they actually want.
A colleague has made me realize that user assistance writers are codependents of bad UI design. Because we explain how the UI really works, we somehow leave our developers and companies feeling like they're "covered" when the users have a bad experience.
When you first ventured into the tech writing ranks, marketing the department was likely the furthest thing from your mind. You already had work to do, so marketing was somebody else’s job.
There are many preparatory steps in technical writing that you as a writer need to take before actually sitting down and start writing a technical document. Here are 7 issues you need to consider in the pre-production phase of your documentation project.
When was the last time you curled up in bed with a really good user-manual just for the sheer joy of reading it? Never? Think that is some immutable law of nature, like the one that dictates all textbooks must be dull as dirt? 'Tain't so, McGee.
How do you stop writing documentation and instead give people the information they need to use a product? You start by understanding your users: their level of expertise, the tasks they need to accomplish, and the problems they are likely to run into. Then you can help them do their work by presenting the information from their point of view and focusing on real tasks, rather than product functions. With this background, you can develop information that is easy to understand, easy to find, and visually effective.
Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists.
Perhaps our headings should focus a bit more on user benefits? For example, "Overview of batch printing - Save time and improve document organization" is a bit more engaging, especially if your customer is struggling with those issues.