Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
In the continuing absence of maturity in the software world, it’s the documentation that has to treat the tool-user with respect. Which is a further argument against Knuth’s Literate Programming. Since it’s all too common to see software toolmakers treat tool-users with short shrift, it’s a useful caution to have the ’software is written in one corner and documented in another’.
Keeping to the four rules articulated here—and never forgetting the axiom—will definitely improve your documentation. If nothing else, recognizing and observing these rules will raise the status of documentation and the people producing it. And they’ll use that raised status in at least two ways.
When I talk to most technical writers, video is a format they haven’t done much with. This surprises me, because I find that, as a user, video tutorials are often the most helpful type of material for me to learn software. Video most closely simulates the universal desire we have for a friend to show us how to do something in an application. Perhaps I’m a visual learner, but the majority of us (some say 60 to 65 percent) are visual learners. But video doesn’t appeal only to end users. Video can be an appealing format for technical writers as well. Creating videos can turn your career around, especially if you find technical writing a little dull.
Microsoft has set some new standards, but they didn’t make it easy to implement them. You can do everything Microsoft did with the possible exception of having the system take action for the user.
This site offers material on a wide range of HTML-related topics. We hope that with this site as a reference, you will be able to create Web sites that can be used by every person on the Internet, regardless of browser, platform, or settings.
You need not be a programmer to begin producing effective, attractive HTML Help or Webpages. You can use pubiished tempiates andauthonng toois and study an existing page’s HTML code to heb you produce pages whiie you learn. Templates allow you to add your content to existing skeleton pages. You can also use an HTML or HTML Heip authoring tooi to create your help. HTML Heip authoring tools aiiow you to add WinHeip-like functionality and ~eamnce to your HTML Hefppages. Using your browser and a text editoc you can study HTML code frum an existing Webpage. Using these methods, you can learn HTML while already producing effective Heip.
IDX Systems launched two separate HTML-based help authoring efforts simultaneously. The results were two very different HTML-based help solutions. One solution emphasized thorough and complete information while compromising accessibility. The other solution emphasized accessibility while compromising thoroughness and completeness. In both cases, the compromises were forced by the limitations of current web technologies. The two writing efforts have now been merged into one solution that uses HTML, database technology, and Active Server Pages.
These are just a few ways in which we can reduce your time spent thinking about the documentation and get you back to your task at hand. Unfortunately our ability to excel at these tasks are limited by two rather large factors:
There’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page.
Quality management is forcing technical communicators to meet the challenge of writing user-centered documentation. Adequate preparatory work would be to categorize potential users according to experience, knowledge, tasks to be performed, and other use-relevant features. Users' requirements and requests should then be incorporated into the document's design.
The following is a conversation I’m calling, “I need your help with some documentation.” The project manager represents a compilation of all the crazy things project managers have said to me over the years.
I’m not sure what you can do to help users continue to increase their knowledge of an application. The problem is that even if you provide the means for advanced learning, whether through tips, newsletters, blogs, or interface notes; users already familiar in performing a core set of tasks are inclined to remain in their comfort zone.
You've heard it from your geeky friends: RTFM, politely translated as 'Read the Freaking Manual.' But what if the manual is unreadable? It's difficult enough to upgrade a motherboard or install new hardware, but it can become a disaster when the only help you've got is a poorly translated, barely legible photocopied manual loaded with vague definitions and unhelpful diagrams. And all too often, that's the way it is.
Documentation, operators’ manuals, maintenance instructions, etc, can never be perfect and satisfy all users. The organization of the documentation, particularly for large systems, will never suit all users and there will always be some errors present. This means the supplier and the user need to cooperate in various ways to avoid the fatal consequences of errors and misinterpretations, and for the improvement of documentation over time.
This paper presents a practical, easily applied approach for designing information from the reader’s perspective. It also contrasts the traditional outline with the new approach. The Corporate Standard: Functional Thinking and Writing is a flexible and reader-oriented methodology that allows writers to get started quickly and readers to find and understand the information they need quickly.
There is most definitely a technical communicator identity crisis underway. Three posts from well respected industry professionals in the span of one month, all dealing with a fundamental shift in an core product development profession. What’s going on here? To put it plainly: documentation now has competition.
Most users will call support before they’ll crack the spine on a shrink-wrapped user guide, but it’s still not okay. It’s not okay because we are still stuck with the tools and environments and processes that compel us to write and deliver those guides. Why are we not listening to our users?
Not many writers consider the positive aspects of users not reading the manual. If you do a lousy job on the manual, or if some SME discovers typos and inaccuracies, you can just laugh it off by saying no one really reads the manual anyway. But consider the opposite scenario where everyone reads the manual. Is this a scenario you want? No.
By having consumers perform furniture assembly themselves, Ikea is able to both lower costs and slowly drive their customers insane. To be fair, Ikea assembly instructions are not that bad. They brilliantly only use pictures, which are clearer than text and require no translation. Still, recognizing that some people may still have difficulty understanding them, I offer this handy explanation of some typical Ikea instructions that came with a bookshelf I recently bought.
One of my goals was to make it easy to get help for using specific parts of our application. Users don’t need to know the name of the panel or feature they are trying to use. They just need to know where they are working on the screen, and they can click through to get the help that discusses that part of the screen.
Multimedia is commonplace in entertainment and the Internet is proliferating the use of multimedia in electronic materials. Online documentation has traditionally been composed of text and some graphics. The proliferation of Intranets and online documentation is pushing the acceptance of multimedia in reference and procedural materials like Help. However, there is little research on the value of multimedia in online documentation nor its effective use.This paper describes an exploratory study done for a Master of Information Science thesis to determine the impact of multimedia on online documentation.
Document control is a major component of any quality system. To implement a document control system, first establish Policies/procedures for generating, approving, issuing, and revising documents. The next step is to design and implement forms and a filing system/data base for managing quality documents. Teamwork and established guidelines can help ease the complexities of implementing a document control system.