Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Making documentation more visual is a two phase process. First comes the brainstorming, where ideas bubble up: the weird the funny, the wonderful, the breakthrough, the lame brain — no idea discriminated against, all equally enjoying the bright, spring air of the creative process. Once You begin to brainstorm you may find putting concepts into graphics is easier than you thought. Then comes the second phase: the hard realization that even if you throw out all the crazy ideas, you still have to pick and choose. You have to develop a strategy for graphic use, one that goes beyond the basic visual unity a good graphic designer can give a document. You have to see the graphics in light of the user's need.
It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.
Although you can position a camera above the phone and record actions on any screen, that kind of recording process limits you considerably. I think it’s more difficult to edit raw video than to edit a screen recording, since a screen recording allows you to more easily manipulate, hide, or add screen elements as needed. I also recommend using emulators or screen recording apps whenever possible because they usually result in clearer recordings.
Deciding to become a technical writer was easy. But finding the experience and the time has proven unforgiving. My job is not based on writing; in fact, writing is rarely needed. I do not have the schooling of a technical writer (yet!) nor the experience, and there were probably a 101 ways to write the documents better. But I’m willing to learn, and the documents I’ve created, while showing that I have plenty of room for improvement, are enough to help me get my foot in the door and transform my job towards the career I want.
The demand for help and hypertext systems has created a problem for many documentation departments, particularly those in smaller companies and inexperienced in creating these forms of online documentation. The scarcity of existing literature compounds this problem. This document provides writers in small companies with limited resources some suggestions to facilitate hypertext project management, planning, design, editing, and usability testing. Also discussed is how to select a hypertext package.
Adapting new equipment to your complete array of jobs, and leveraging your new investment to help your business grow and become more competitive, is part of an ongoing process that is much more important that the initial implementation. It's a process that requires an on-going partnership and several levels of support from your technology vendor-- beginning with basic maintenance and repair and optimally evolving to a true interactive partnership.
If you are like most technical writers, your procedures have automatically numbered steps (whether in tables or text), Microsoft Word provides two relatively simple ways for you to cross-reference a step number.
Localization includes translating, explaining, and adapting a document for use in a specific culture. This article presents the case of a form for reporting the findings and decisions of pre-production meetings held during development of electronic products. The need to localize such a document may seem less obvious or critical than the need for sales documents like manuals, but this case demonstrates the same cultural requirements and, furthermore, the requirements of corporate differences. To meet local needs, the comprehensive preparation that localization requires should follow specific methods in each step of a process corresponding to the general writing process, like the stages defined in common technical writing texts. The deliberate use of an effective writing process to localize documents will improve results.
Budget and time constraints often force technical communicators to produce manuals that are less than effective. One reason is the time they take to analyze their document's users. Normally, user analysis involves demographic, or organizational, or psychological approaches or combinations. Rarely will they evaluate the culture of the user and determine what that means for developing the document. Typically, localization will edit the document for cultural elements, but that is an expensive and time-consuming process. This article discusses the cultural elements in developing a document and shows, through a comparison of two mythical cultures, how the document will differ when organized for those two cultures.
Many technical writers are developing usability skills and leveraging them to help improve the product interface. Help is being delivered within the interface itself. Drop-down lists of topics related to an interface component, hint text below a GUI field, and other such embedded user assistance models allow users to get help without leaving the application interface.
Technical communicators today must document complex applications used in complex environments. Information about users and use models is important under these conditions, especially if documentation will be presented online. Customer partnering, a method of information gathering that supplements surveys, contextual inquiries, usability testing, and interviews, provides a way of involving the users of complex applications in the design of information delivery systems. We used this method to help a client gather important information about user and use models and design a new information library for complex server computer systems.
Documentation and package design play a major role in customer satisfaction. The author tested three sets of wordless documentation by building pieces of furniture from three different manufacturers. While the construction methods, packaging, and wordless documentation methods were on the surface very similar, small differences had a significant impact on the usability of the instructions and the overall customer satisfaction with the documentation and the product. Decisions that were handled differently included visual verification of parts, whether or not extra hardware was provided and how it was provided, the appropriateness of the hardware, the quality of the hardware, the need for additional tools, and the care evidenced in packaging and labeling of parts. From these experiences, she makes recommendations for enhancing customer satisfaction that apply not just to wordless documentation, but to other consumer products.
Customers avoid web-based customer support if information is not relevant, out of date or hard to find. Without a business commitment to addressing these issues, customers will continue to prefer contacting a service representative by phone.
Collections of technical documentation vary in their delivery media, file format, user interface and degree of integration of the component documents or information. This paper looks at definitions and attributes of collections before reviewing the development of book- based, customized CD collections in a company operating in a fast-changing industry. Issues arising from this case study are explored and findings are used to identify a broad categorization of collections and build a starting point check list for collection design. Major issues in collection building are summarized.
Doc-To-Help gives Help authors complete control over the look, feel, and content of a project's printed manual, Windows Help system, HTML files, and HTML Help system. Maintaining different content is controlled using Doc-To-Help's conditional text feature, which allows authors to mark content for print-only, online-only, WinHelp-only, and so on. In this article we discuss how you control the appearance of the printed manuals and Help using Word templates, and HTML output using cascading style.
Sure. We’ve been reducing word count in procedures for some time. It’s time to do more, however. As noted in an earlier post, we have to think mobile. Think small screens and small devices. Screen real estate will be at a premium.
If you need the collaborative aspects of a Wiki combined with DITA's modular topics and publishing capabilities, then DAISY might just be the system you need--and it's free. DAISY provides WYSIWYG editing for Wiki pages that can be combined to publish books, either in a PDF or as a single HTML page.
Translation of documentation has traditionally been a major expense in the globalization process, especially if translations are required for multiple languages. The Darwin Information Typing Architecture (DITA) is an XML-based architecture for creating topic-based and information-typed content. It provides a number of features that, in addition to supporting high-quality information delivery, allows for more efficient and reliable localization of information. This article provides both an introduction to DITA and a discussion of DITA features that enhance document globalization.
In this article, we outline how IT analysts can effectively make determinations about the value of process documentation, and in the process, transform a potential scourge into a possible blessing.
The old school of software interface design and document writing took the view that if the user could find the information someplace, the user could use it. But simply sticking in details ignores how readers access and process information.
Declarative information is often considered to be of little value to software manual users, for two reasons: some research results state that it is consistently skipped by users, and other research results show that declarative information does not enhance task performance. This study puts these conclusions to the test, because the research underlying them does not support such general conclusions. Two experiments are conducted to collect quantitative data about the selection and use of procedural and declarative information and to investigate whether or not the use of declarative information affects task performance and knowledge. A new technique for measuring information selection was developed for this purpose: the click and read method.
One of the hottest topics these days in Information Architecture circles is documentation. This is probably partly because the IA's role is so ill defined. Our jobs sit perched between engineering and graphic design: go too far in one direction, we're doing the coding, go to far in the other and we are doing the design. Neither role maximizes the architect's key skills; defining the organizational structure and behavior of the web site or application. An IA is most effective when they leave implementation and final graphic design out of the mix. The documents they create to express this have to be crafted with equal skill and diplomacy.