Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
The use of three simple tools can assist the documentation manager, from start to finish, on any new project. A revamped pubs plan, a new concept with engineering worksheets, and a matrix of modularized information are all utilized with a slightly new twist. The Pubs Plan is redefined to help you launch your project with a team approach, identifying issues, and proposing solutions. The Engineering Worksheets list all the critical pieces of information your writers/illustrators need for each component of the product. These pieces of information are then tracked by completion date on an Information Matrix. These documents work together as complimentary management tools that can be easily developed and scaled to the complexity of any project.
Software documentation can be difficult to review, so it helps to have some editing guidelines to keep you focused. Let's face it; software documentation isn't exactly exciting reading material. But you should be able to complete the job in a productive manner if you keep your coffee cup full and follow the editing guidelines below.
Much has been said about the creation of modular documentation - from content management systems, to information architecture, to delivery forms, to the usability of modular content (content being easier to use, easier to understand, and easier to find), and so on. However, not much has been said about the editing of that content, and what the editor's role is in such an environment.
The authors have come up with eight guidelines and three concrete suggestions on best practices for editing modular documentation, including ensuring that all topics are standalone, that titles are unique and descriptive, and more.
Technical writers sometimes fall into the trap of thinking that the user is stupid. I have often heard technical writers say things like 'well, if the user can't figure that out, maybe he’s in the wrong job!'
Typographical errors and grammatical blunders affect the aesthetic appeal of documentation, and common belief is that they affect usability too. Many readers, however, seem not to notice such errors unless they are very frequent or flagrant. We thought it would be interesting, and perhaps useful, to test experimentally the effect of such errors on users’ perception of the information and on their performance with the product that the information supports the product.
Defining the quality of information has long been a controversial item. Many different theories and methodologies have been brought forward; almost all share at least one common basis— Typographical errors lower the perceived quality of information. In this experiment, the first of a planned, series, we examined the effects of typographical on the user’s perception of the quality of the product and documentation. The conclusions of this first study, and the implications we can make draw them, are presented in this paper.
It would be useful to determine how much effect errors in product documentation have on users, if errors do not seriously interfere with product use. In an effort to start collecting information on this issue, we designed an experiment to explore the reactions of users to a simple interactive program with flawed documentation. We hypothesized that the product quality would be judged in part by the quality of the documentation, if the errors in the documentation interfered with task performance. We also hypothesized that some but not all users would be sensitive to documentation errors and would downgrade their rating of the program and the documentation based on these errors. The results of our experiment are presented in this paper.
It would be useful to determine how much effect errors in product documentation have on users, if the errors do not seriously interfere with product use. In an effort to start collecting information on this issue, we designed an experiment to explore the reactions of users to a simple interactive program with flawed documentation. We hypothesized that product quality would be judged in part by the quality of the documentation, if the errors in the documentation interfered with task performance. We also hypothesized that some but not all users would be sensitive to documentation errors and would downgrade their rating of the program and the documentation based on these errors. Our experimental design is described in this paper.
The tools and techniques utilized in the technical communications profession are constantly improving and changing. Information Technology (IT) organizations devote the necessary resources to equip and train engineering, marketing, and sales teams, but often fail to do so for technical documentation teams. Many IT organizations tend to view documentation as an afterthought; however, consumers of IT products frequently base their purchasing decisions on the end user documentation's content, layout, and presentation. Documentation teams play a unique role in IT organizations as they help to build and create a public identity through end user manuals and the corporate website, as well as maintain intellectual knowledge through knowledge sharing and management. The technical communicator 'makes sense' of complex engineering specifications by creating user-friendly manuals for the layman. The practitioner who compiles and records this complex information is a valuable resource to any IT organization. Therefore, on-going training for technical documentation teams is essential to stay competitive in the fast-paced technical market. Technical communicators in IT organizations who only write end user manuals are becoming a rarity. Research indicates a marked trend toward technical writers in multiple roles and varied responsibilities that include web design and development, and business systems analysis functions. Although these added roles and responsibilities require training on some of the newer software tools and more complex programming tools, technical communicators are experiencing difficulty keeping pace with these tools. This article discusses technical documentation teams in IT organizations and provides an on-going training assessment to help technical documentation managers identify their team's strengths and weaknesses. In addition, measures and results from a study conducted at eight IT organizations, are provided to show the effect of how the integration of on-going training for documentation teams enhances individual competency and improves team performance.
Should instructional texts be purely technical, with a focus on effectiveness and efficiency, or should they also focus on satisfying and motivating users? Good arguments have been made for paying attention to motivational aspects. But only analyses of existing instructions have been published so far, and guidelines for making user instructions motivational have not yet been studied carefully. This article presents motivational strategies and an experiment to test their effects. The results show that motivational elements have little effect on users’ effectiveness and efficiency in performing tasks, their product appreciation, and their self-efficacy, but they do increase users’ appreciation for the instructions.
Online tools can improve documentation management in several ways, depending on management goals of cost, schedule, or quality. Cost management tools need integration with automated status and quality assessment tools. Workflow simulation tools show great promise for avoiding bottlenecks in the document development process. Automated tools can enforce quality checkpoints and provide model document templates. The continual evolution of online documents will require new management approaches and goals.
A basic prerequisite for good content strategy is that the content should be of good quality—accurate, concise, and complete. An efficient workflow with professional technical communicators creating high-value information is typically the least expensive option (better, faster, and cheaper).
When technical communicators have a strong personal attachment to the publication they are preparing, this attachment may interfere with the design and testing of the publication itself. Documents developed by solo authors tend to be late, buggy, and exceedingly difficult for others to maintain. 'Ego-less' methods---collaborative and structured---break the proprietary connection between the writer and the book; in so doing they permit the most powerful tools of engineering and testing to be used. But they also reduce the satisfactions of the communicator's job.
Whether software documentation is designed for a company’s internal users or for a variety of end customers, one thing is for certain: Documentation that is well written, well structured, easily accessible, and thoroughly compliments the software it supports can play a significant role in a product’s overall success. And it doesn’t matter if the documentation stands alone or it is integrated with the product. As long as it is properly planned, developed, and configured, success is eminent.
Overview topics play an important role in creating a positive user assistance experience. Unlike procedures, which deliver critical information on how to solve a problem quickly, overview topics fill in the conceptual details and background "story." Here are some tips for writing thorough and informative overviews.
Kiosk design is an inevitable extension of the development of online documentation. Technical communicators are now frequently being asked by their employers to create such forms of communication. They must learn about kiosks from the new perspectives of their evolving technologies, applications, audience reactions, social contexts, and information design. Finally, technical communicators must begin to view kiosks as an emerging new genre that requires both analysis and creativity.
Procedures are the meat and potatoes of technical writing. They help users get the job done. Follow these tips for writing clear and useful procedures that your users will appreciate.
When technical communicators are part of a development team, we can do much more than write manuals. Our analysis and communications skills, user perspective can help launch a project team into productivity. We have a unique skill set which enhances the productivity and quality of the development process. By involving us early, we can assume technical communications tasks that developers otherwise perform. This exposure gives us a broader and deeper understanding of that which we communicate. Our involvement means better communication; with users and team members, and in deliverables and development processes.
Email has become a universal conversation mechanism for business to business notification, customer to business communication, you name it. If you’re not doing so already, you can add email links so that readers can send emailed feedback to your technical documentation team. With advanced mailto markup you can automatically enter a subject line, indicate who the email will go to, as well as enter courtesy copies and blind courtesy copies to additional people. Your inbox should not be overwhelmed with feedback emails, but a link should give customers the feeling that their comments are collected and concerns addressed. This is conversational documentation at its simplest.