Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
This study compared two evaluation techniques, Usability Testing and Cognitive Walkthrough, in their ability to identify errors in aviation maintenance documentation. The techniques were evaluated to see how much unique information they each produced as well as the type of errors identified. Results showed that the techniques were complementary in their findings and both are recommended in the development of technical documentation.
By means of the tekom guidelines (check list) the technical author can particularly check the documentation of a product. However it is not the product which can be checked by means of this check list, but only the product’s documentation.
Increasing competition, generational differences, widespread social awareness, and customer demand for higher quality products and services make it necessary to ensure that the right protections are in place. Other reasons for the increased attention include the numerous reports of corporate scandals and corruption, along with ensuing legislative regulations in today’s global economy. This article describes some of the specific causes.
How can you guarantee a clearly understandable user manual? Is it even possible to measure the quality of technical documents or does comprehensibility merely depend on the reader? To answer these questions for the Porsche AG, content analysis provider semiotis³ developed a model to help measure the quality of documents.
To learn software, passive users prefer to have concepts and procedures clearly spelled out for them, while active learners prefer experimenting with the program. When designing a manual, writers should keep both types of users in mind. Writers at WordPerfect are currently experimenting with minimalist design models that encourage active learning. One such model is an “On Your Own” section which guides users through creating a document. Another model is a visually oriented “Applications” section which provides tips on how to create a document.
Visual Basic provides several hooks for easily connecting to WinHelp. In addition, you can call the WinHelp API from anywhere in Visual Basic for additional access to help. This document is intended to show you how to hook WinHelp to Visual Basic 5 and later without using add-ons.
I’ve been collecting examples of wildly inconsistent writing lately. I’m not sure why these have stuck out to me, but when I think of book sprints and community writing events, consistency is an important, though sometimes difficult, goal and outcome.
Software products have found ways to share content and reuse content to deliver more value with limited resources. For example, fantasy football web sites share player news, injury reports, and game statistics. Security products often reuse security announcements and warnings from trusted sources, and present them as rebranded content. We are also seeing software vendors using Twitter and RSS feeds to distribute information and announcements. The next step is when these information feeds are integrated into the product user interface itself, making it the one stop resource for all the information needs of its users. No more need to use google when your product itself delivers the answers to all your questions from the sources you trust.
The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete "Answer Station" that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This paper discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.
The web allows us to easily provide updated documentation to our users, but why stop there? There is more to making users successful quickly than just providing documentation. By creating a complete 'Answer Station' that is accessible from the application or product, we can not only direct users to that updated documentation, but we can also provide information about technical support, consulting, training, sales, etc. This article discusses writing a proposal for an Answer Station, determining content, working with other departments to gather information, designing the site, making that design work with an existing corporate website, dealing with tool issues, and finally, going live.
This study suggests that documentation is a complex technical communication genre, encompassing all the texts that mediate between complex human activities and computer processes. Drawing on a historical study, it demonstrates that the varied forms given to documentation have a long history, extending back at least to the early days of commercial mainframe computing. The data suggest that (1) early forms of documentation were borrowed from existing genres, and (2) official and unofficial documentation existed concurrently, despite efforts to consolidate these divergent texts. The study thus provides a glimpse into the early experimental nature of documentation as writers struggled to find a meaningful way to communicate information about their organization s developing computer technology.
While there’s still discussion about how best to define content strategy, I think that most everyone agrees on a couple of key points: A content strategy is, well, a strategy. A strategy, by definition, provides an overarching framework within which specific actions can be planned and executed. A strategy gives purpose to every action, but a strategy is more than just the sum of the actions. It’s not tactical: for example, it doesn’t dictate things like how a style sheet should be coded (although it might contain broad guidelines for how the styles should look). A content strategy should be broad enough to encompass all kinds of content: content from all over the organization, as well as (increasingly) from the user community; and content that can be distributed in a variety of formats.
This article is for software developers who have never implemented context-sensitive help. It explains the concepts and the basic types of context-sensitive help. A demonstration application with context-sensitive help is available.
Context-sensitive Help is assistance that is appropriate to where the user is in the software application, and what they are trying to do. Carol Johnston's article describes what programmers and technical authors need to know about Context-sensitive Help.
This podcast talks about the convergence of web 2.0 with help documentation. It mentions examples of Web 2.0 sites, such as Flickr, Payscale, and Digg, and what help files need to incorporate these same Web 2.0 features.
Offers a strong recommendation to read Anne Gentle’s Conversation and Community: The Social Web for Documentation, which provides tips for incorporating wikislices, screencasts, and comment/feedback systems, into your user assistance.
Technical communication is changing rapidly. If you’re not ready for that change, it’s going to really catch you off guard. Anne Gentle's book Conversation and Community is an excellent guide to rolling with those changes, and for staying ahead of them. This article takes a close look at the book.
The SIS Conversion Team and Electronic Media Development Team support the Service Information System development by providing data on CD-ROM for Caterpillar customers. This unique project covers eighteen different publication types, requires conversion of 750,000 pages and more than a million gray scale and line art images. The targetted data includes Parts Manuals and a variety of technical documents that were written to cover all Caterpillar machines and engines built since 1977. The conversion to electronic images and SGML-tagged text, and subsequent EMD processing and distribution via CD-ROM required extensive development efforts and a significant investment in leading edge technologies.
Multimedia has proven its ability to sell products and educate users. But can it also perform tasks traditionally done with conventional paper documents? Yes. This demonstration shows how several hardware and software documents were converted to multimedia and provides a plan for converting your documents. You learn whether to display, speak, or just eliminate existing text. You see how to replace action words, descriptions of motion, and arrows with animation. YOU see how sound can guide rather than distract the user. You also learn to use interactivity to give control to the user. Along the way you see the compromises needed to keep the project on schedule, within budget, and down to size.
Big producers of equipment and systems of all branches often have piled up enormous volumes of product documentation in various formats on different media over long periods. How does one deal with that in the Internet age? How will brochure-like product catalogs be converted to type-specific clickable web pages, and printed price lists to present-day worldwide retrievable tables? Experiences with a large converting project show the process to achieve such document management.
You’re told that you need to move your content to XML. You have loads and loads of unstructured content. It’s in FrameMaker, Word, other desktop publish applications, or even more fun: it’s on paper.
After being laid off from Lenovo (formerly IBM) where I documented small computer accessories for many years, the need to update to a different brand of technical writing became evident. In interviews, when asked if I had experience with software documentation, I would say that I included information on device drivers. That’s close enough, right? However, in my current work at SAS, I have since discovered that documenting computer software is much more complicated. It’s like the difference between planning and preparing a Thanksgiving meal and microwaving and setting out the game-day snacks.
Using hypertext and paper creates a successful trip for the user of an interactive, mainframe software system. Building integrated, complementary documentation requires thoughtful planning, careful organization, and skillful implementation. The resulting product needs the cooperation of the entire team.
The idea of a Book Sprint is that you can get lots of documentation written in a focused amount of time with the right team and some amount of content already in place. Gathering people in the same room when possible is extremely helpful and motivating as well.