http://tc.eserver.org/dir/Design/Documentation A listing of the most recently indexed works about Design and Documentation in the field of technical communication. en-us Copyright (c) 2005-08 by the EServer. All rights reserved. tclib-editorial@eserver.org (TC Library Editorial Board) webmaster@eserver.org (Geoffrey Sauer) http://tc.eserver.org/images/newlogo.gif http://tc.eserver.org/dir/Design/Documentation http://tc.eserver.org/35627.html http://tc.eserver.org/35627.html Seth Godin believes that everything reflects what you stand for—right down to your technical documents. Ever looked at Apple’s tech docs? http://tc.eserver.org/35677.html http://tc.eserver.org/35677.html The shift in information development from a narrative to a modular writing style reflects the established shift towards modularization of source code. What can information developers learn from software developers? What are the challenges and benefits of the modular approach? http://tc.eserver.org/35435.html http://tc.eserver.org/35435.html What does structured authoring mean to you? Structured authoring is a publishing workflow that lets you define and enforce consistent organization of information in documents, whether printed or online. What it means to me: defining a goal and assembling architected topics to help the reader achieve that goal. http://tc.eserver.org/35407.html http://tc.eserver.org/35407.html While I'm a firm believer in the primacy of content over appearance, aesthetics are definitely a part of drawing people into documentation and engaging them. There's nothing wrong with making online assistance or a printed manual attractive. It doesn't need to be a beautifully-designed work of art, but it should be something a little more than blocks of black text on a white page. http://tc.eserver.org/35301.html http://tc.eserver.org/35301.html I have no idea what our users want. I do know they want information, and I know they want that information to be kept up to date as our product evolves and as far as those basic needs are concerned, I’m happy that we are meeting them. Beyond that I admit I’m not really that sure. http://tc.eserver.org/35210.html http://tc.eserver.org/35210.html As help systems continue to evolve, whatever name they are called, we will increasingly have to face responsibility for their content, and bring their expertise to what we write. The new systems provide us with all the required tools that tell us the problems with their content. It is up to us to leverage that information to provide better content, and act as ambassadors for products that we write. If writers can go a step ahead, and use their help information to sell products, and reduce the burden on customer support, we would have truly arrived. http://tc.eserver.org/35190.html http://tc.eserver.org/35190.html This Fast Track tutorial demonstrates two methods to call Context-Sensitive Help in a Web Form. We'll discover how Unobtrusive DOM/JavaScript achieves the desired result in calling Context-Sensitive help, and demonstrate how to keep the Structure, Presentation, and Behavior layers of a web page completely separate from one another ensuring good practice with current web standards and accessibility rules. http://tc.eserver.org/35158.html http://tc.eserver.org/35158.html When it comes to an about page, think outside the box. Try to think of something new and creative that’s different form the rest of your site. Of course display images of you / your staff, and descriptions of each, but try to lay it out in a very fun way, whistle keeping it clean and readable. http://tc.eserver.org/34711.html http://tc.eserver.org/34711.html Part of the problem in our attempt to demonstrate value is that our help deliverables look the same as they did 15 years ago, more or less. Online help and a PDF manual. It’s not a format that engages users. The web marches forward with innovation after innovation, while the technical communicators are figuratively hunched over keyboards, staring at CRT monitors, wearing 1950s horn-rimmed glasses, typing away. http://tc.eserver.org/34637.html http://tc.eserver.org/34637.html Even though your customers may not read manuals, your tech support team probably does, which means someone is reading the manuals and using them to help others. But if your users find it easier to call someone, wait on hold for an agent, and then ask the agent a question rather than find the answer in the help, maybe your help materials aren’t very usable. Maybe increasing the usability of your company’s documentation could alleviate the need users feel to seek answers from another source. http://tc.eserver.org/34638.html http://tc.eserver.org/34638.html In this presentation, Joe Sokohl talks about gathering user research prior to designing and implementing your help deliverables. http://tc.eserver.org/34639.html http://tc.eserver.org/34639.html Dan Roam explains that drawing pictures can help you solve problems. He says the first rule is to “collect everything possible up front.” After collecting all your information, you then “lay it all out where you can look at it.” By laying out all the information, you can grasp the whole of it, make connections between various parts, see the important sections, and recognize patterns. http://tc.eserver.org/34613.html http://tc.eserver.org/34613.html What FAQ pages have become are elephant graveyards of non-information, the equivalent of the Miscellaneous file folder, the place where information-we-didn’t-know-where-to-put was dumped. The challenge of creating a FAQ page that customers will find useful has several aspects to it, but can be accomplished with a lot of planning and a little strategic work. http://tc.eserver.org/34587.html http://tc.eserver.org/34587.html 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. http://tc.eserver.org/34548.html http://tc.eserver.org/34548.html A musing on the need to balance documenation that looks good with documentation that has substance. http://tc.eserver.org/34489.html http://tc.eserver.org/34489.html 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. http://tc.eserver.org/34485.html http://tc.eserver.org/34485.html When documents are built from components, and the components can have contextual variations, it becomes possible to construct built-to-order documents "on the fly", in response to user demands, rather than having to pre-create static versions of all possible variations. Once such a system is in place, it becomes possible for users to further customize the results by modifying the list of selected topics, rearranging their order, or even by adding new topics. http://tc.eserver.org/34444.html http://tc.eserver.org/34444.html Why do product manuals sound formal and stiff-upper-lipped? Why don’t users read manuals? These questions have haunted the precincts of Technical Writing for quite some time now. From what I have seen in Indian writers, I am forced to conclude that English Composition, as we were taught in school, is the culprit. http://tc.eserver.org/34385.html http://tc.eserver.org/34385.html Citing the rise of graphic novels, comics, and in particular, Google’s new web browser Chrome, which has a comic-book-style manual, Opsteegh argues that technical communicators can learn a thing or two about conveying information from graphic novelists. http://tc.eserver.org/34378.html http://tc.eserver.org/34378.html Users would save time by reading the manual, but instead they try to figure the application out themselves and then get lost/frustrated as they end up spending even more time getting up to speed with the application. http://tc.eserver.org/34093.html http://tc.eserver.org/34093.html User assistance can add value to a product or Web service’s business model by influencing how deeply users adopt new features or services. As more products employ pay-as-you-go models like that of SaaS (Software as a Service), the contribution user assistance makes becomes increasingly more important. http://tc.eserver.org/34025.html http://tc.eserver.org/34025.html Technical writing has its mechanical aspects that need to be mastered. A good technical writer must know how to use English effectively as well as various software products to produce acceptable technical documents. But I wish technical writing were all about that. The hardest part comes before one even sits down in front of a computer to type the first word. The hardest part in documenting anything is organizing the information in a way that makes sense from the user’s point of view. Otherwise a technical document suddenly looks irrelevant. http://tc.eserver.org/33894.html http://tc.eserver.org/33894.html I should never fully trust anyone on a project. I don’t mean this disrespectfully, because I work with competent, talented professionals. But no one has the full picture of how the application will truly work. The quality assurance (QA) engineer usually has the clearest picture. The program manager and project manager are often living in a slightly different world, full of a vision of how the product should work and how they expect users to interact with it, but sometimes they’re missing important nuances in the actual implementation. The interaction designer builds prototypes and assumes the developers will build them to spec, but since the prototypes are usually HTML-based, and not in Java or .NET, variances are inevitable. http://tc.eserver.org/33849.html http://tc.eserver.org/33849.html Here's a quick tutorial about screen captures, thus the title. If you're not sure what a screen capture is, then think about the pages you've seen lately. Maybe some of them have had specific sections of the desktop or a program made into an image. It was almost as if they captured part of the screen as an image. http://tc.eserver.org/33865.html http://tc.eserver.org/33865.html In recessionary times, organisations should focus on getting sales from existing customers - so customer retention becomes ever more important. http://tc.eserver.org/33694.html http://tc.eserver.org/33694.html I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly. http://tc.eserver.org/33424.html http://tc.eserver.org/33424.html Often conflicting pressures to produce communications that better fit customer demands as well as stay within tightening constraints on budgets and schedules are leading many technical communications organizations to a topic-based approach to authoring. In fact, 58% of participants in Aberdeen Group's October 2008 DITA and the Technical Communicator’s Transformation study report that they currently follow author content in a topic-based manner, with a vast majority of those remaining planning to implement one in the future. A topic-based approach promotes greater content reuse and is seeing a considerable impact on the authoring efficiency of technical communications projects today. The benefits of topic-based authoring can be compelling, with findings from the The Technical Communicator’s Transformation study indicating that when pursued the right way, topic-based authoring can have a broad range of benefits, enabling an organization to meet authoring and localization cost targets as well as documentation quality expectations, among others. However, as the adoption of this approach spreads, the advantages seen by today's leading organizations will flatten out. This Sector Insight provides a guide for current adoption of topic-based authoring and those still considering it; outlining the changes that are expected to take place in as topic-based authoring goes mainstream. http://tc.eserver.org/33338.html http://tc.eserver.org/33338.html Information Mapping is a proprietary method for the analysis, organisation, and presentation of information. It is based on the needs of the users and their purpose in using the documentation. Information Mapping has three parts: analysis, organisation, presentation. http://tc.eserver.org/33156.html http://tc.eserver.org/33156.html Apple's first user manual was largely the creation of Ronald Wayne, Apple's third founder, recruited from Atari by Steve Jobs for a 10 percent stake in the new company. Wayne not only wrote the entire 10-page booklet, he also drew the intricate cover logo depicting Isaac Newton beneath an apple tree. http://tc.eserver.org/32824.html http://tc.eserver.org/32824.html Before you release a product, have some people use it. From these "test users" get solutions to problems, tips and knowledge that would help your real-life Users. Put that information in your User Documentation, and on your product support website. http://tc.eserver.org/32540.html http://tc.eserver.org/32540.html When initiating or expanding the role of user-centered design (UCD) in an organization, consider documenting UCD best practices as they fit within existing processes and the best practice of other areas. Such documentation communicates the role and value of UCD throughout the organization in terms familiar to your organization. Because what best practices means varies from company to company, there is no single way to do this. Here are some questions to consider. http://tc.eserver.org/32349.html http://tc.eserver.org/32349.html Users turn to help to look for a specific question, just as someone consults an encyclopedia for a specific question. No one reads the entire encyclopedia/manual, nor is anyone expected to. Well-written encyclopedias allow users to find information through indexes, tables of contents, alphabetical organization, and search fields. http://tc.eserver.org/32171.html http://tc.eserver.org/32171.html If you document everything, you are giving everything an equal weight. Do that for a complex system, and you are buried in detail. In any system there are some aspects that are more important than the others, key aspects of the system that once understood, will help someone to learn more. The art in documentation is to find how to document these aspects as clearly as possible. In this you emphasize these areas, and leave the details for the code. http://tc.eserver.org/32144.html http://tc.eserver.org/32144.html In my work with Bumblebee I use an approach I call 'User-Guide-Driven Development,' or UGDD for short. The mechanics of UGDD is similar to that of Test-Driven Development (TDD), but before I write the test for a feature, I write a snippet of the user guide describing the feature I am about to implement. http://tc.eserver.org/32096.html http://tc.eserver.org/32096.html A brief comparison of two often-confused concepts. http://tc.eserver.org/31893.html http://tc.eserver.org/31893.html In this podcast, Nicky Bleiel says we should talk to as many users as we can — conducting on-site visits, sending surveys, gathering information from Marketing, Support, and other departments — so we can have a better understanding of our users’ needs and the formats and mediums that will work best for them. After completing this audience and needs analysis, we can then go out and create the deliverables that will best serve our users. http://tc.eserver.org/31894.html http://tc.eserver.org/31894.html 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. http://tc.eserver.org/31780.html http://tc.eserver.org/31780.html With all the talk about Web 2.0 and the attendant technologies, are readers actually being better served by documentation now than they were in the past? http://tc.eserver.org/31748.html http://tc.eserver.org/31748.html The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert? http://tc.eserver.org/31738.html http://tc.eserver.org/31738.html Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce. But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help. http://tc.eserver.org/31740.html http://tc.eserver.org/31740.html In Publishing 2.0, Tim O'Reilly says Web 2.0 is 'any network effect that makes a system better the more people use it.' Web 2.0 isn’t just user-generated content; it’s harnessing the collective intelligence of your users to make your system better. http://tc.eserver.org/31582.html http://tc.eserver.org/31582.html This blog discusses documents and information designs “in the wild" - especially those that are exceptionally good or exceptionally bad. http://tc.eserver.org/30766.html http://tc.eserver.org/30766.html Every webmaster nourishes the dream that his or her website will make it the big way. This is very much human because people carry out any task in ardent hope. What is more human out here is that earthy fellows like us base our aspirations more on speculation rather than specific set of steps undertaken to bring the dream a bit closer to reality. And this is not all, particularly in case of growth of a site which brings newer problems in the wake of its growth. It cannot be disputed that you can probably get some good web hosting on economy price. But if you expect top of the line service on this price, acknowedge gracefully that your are just asking for the moon. Probably you are not catching up with wisdom that business needs decisive investments. http://tc.eserver.org/30610.html http://tc.eserver.org/30610.html The success of any technical document depends on the reliability of information presented in the document. A database can provide an informal mechanism for exchanging information about product development and support, The database system should have a user interface that is easy to use and does not require too many operations. Factors that must be addressed in the design, testing, and implementation of the database include the type of information, ownership, system maintenance, access control, and system development tools. Writers, who have special expertise in information gathering, can take the initiative and build support for the project. http://tc.eserver.org/30622.html http://tc.eserver.org/30622.html Faced with growing demand from customers for specific courses, addressing only their needs, in very short time-frames, we had to re-examine the way we worked. Patching together one-shot customized coursework was labor-intensive for a non-homogeneous and unsatisfactory result. Each new customer request required repetition of the same amount of effort. With reduced turnaround time and dwindling human resources, a solution had to be found. http://tc.eserver.org/30555.html http://tc.eserver.org/30555.html A features-based approach to documentation is appropriate for reference manuals, where the goal is to provide information on something the reader already knows. This article explores how to meet the needs of the reader when providing documentation for user manuals. http://tc.eserver.org/30491.html http://tc.eserver.org/30491.html From the customer's perspective, an important and visible part of a product or service is its documentation. Bellcore's Technical Publications (Tech Pubs) organization uses a Quality Assurance (QA) program that focuses on enhancing customer satisfaction through delivering high-quality documentation. This program emphasizes a 'network' approach to documentation development, whereby technical writers can most efficiently use the support network of QA reviewers and management available to them. The Tech Pubs QA program draws on the needs of clients and the expertise of technical writers to strive to achieve the highest level of quality possible in producing documentation. http://tc.eserver.org/30505.html http://tc.eserver.org/30505.html In an effort to improve the quality of our documentation, our Information Development department personally visited over 80 of our customers in 10 different locations across the United States. Our goal was to find out what we needed to do to create documentation that would satisfy our customers' needs. We came up with a process for planning our visits, gathering the information from our customers, implementing their requirements, and increasing communication with them. From the visits, we not only made changes that immediately satisfied our customers, but we created an environment for them to work with us as a team. http://tc.eserver.org/30506.html http://tc.eserver.org/30506.html It is important to recognize that because we all differ in our experience and background the learning process is different for each of us. Consequently, in our documentation we should by to put users on an equal footing by, for example, clearly and exactly defining terms we use and including a glossary. We can also put everyone on an equal footing by using 'bridges to understanding,' from analogies, examples, and metaphors to mnemonic strategies. For overall comprehension, we can employ 'frameworks,' from conceptual maps to road maps, that give patterns of meaning to what we say. http://tc.eserver.org/30382.html http://tc.eserver.org/30382.html Recent research focusing on a minimalist approach to computer software documentation has explored ways to design computer software tutorials and workbooks for users with an active learning style. The principles of minimalism and active learning styles, however, are less frequently applied to traditional reference manuals. This paper reviews several elements of minimalism and suggests ways to apply strategies for active learners to traditional reference manuals. http://tc.eserver.org/30400.html http://tc.eserver.org/30400.html When purchasing complex software products, users frequently receive large quantities of information; however, to use the product efficiently, they need a visually obvious starting point that helps them locate the specific information they need. With maintained With the quantity and diversity of information, customers need to be able to find the information they need without flipping through endless pages. In order to give the users a starting point in all of the printed and ASCII file information. we created a document entitled the Guide to products, users can use the features available with a new release most efficiently if they have an overview of the major changes to the product and to the information about the product. By using visual devices and creating an overview document. for each release, technical communicators can decrease their costs and increase users' productivity. http://tc.eserver.org/30315.html http://tc.eserver.org/30315.html People who follow the right trends will someday lead them. Such an opportunity now lies in the hands of technical writers, as the computer field moves toward standardized, graphical, easy-to-use interfaces. http://tc.eserver.org/30135.html http://tc.eserver.org/30135.html This paper presents three methods of user assistance: role models (simple demonstrations), guides (structured walk-throughs), and coaches (active assistants). After a brief introduction, potential uses, available development tools, and additional information sources are discussed for each method. http://tc.eserver.org/29987.html http://tc.eserver.org/29987.html Software user guides have traditionally provided assistance when the user requested help. Context-sensitivity enabled help systems to predict the most appropriate topic to present. For Windows applications, the move from Microsoft WinHelp to the new Microsoft HTML Help format allows user instructions to be presented in the same window as the application. This offers technical authors some extraordinary opportunities to provide intelligent, predictive, interactive help without the user having to request it. In this paper, we will explore one of the first such interactive help systems (for the Archivist e-mail archiving software), and see where the technology is moving. http://tc.eserver.org/29770.html http://tc.eserver.org/29770.html Technical writers make distinctions between the types of documents they create: user guides, reference manuals, tutorials. But do users really understand these document types? How do users look for different kinds of information--and how do we, as technical writers, make it clear to them what types of information are available? This paper presents results of usability evaluations of documentation for electronic design automation software, showing how a writing team tried to improve the categorization and presentation of document types. http://tc.eserver.org/30285.html http://tc.eserver.org/30285.html Several Texas Instruments writing groups are using a new manual publication method that emphasizes more customer interaction early in the manual development process. This emphasis brings project teams and customers together to accurately define their expectations for the documentation. Writers chunk information as they create the manuals, which allows reviewers to look at the small pieces one at a time and to focus only on those chunks containing information pertinent to their particular expertise. This method defines manual parameters early in the process, which simplifies usability testing. http://tc.eserver.org/29535.html http://tc.eserver.org/29535.html An overview of web design methods, including a survey of questions one should ask during the process. http://tc.eserver.org/29444.html http://tc.eserver.org/29444.html Although some zealots have proposed eliminating printed information entirely in favor of online help systems, Adobe Acrobat files, and even e-books, discarding printed books may prove less effective than simply modernizing them. Scrolls are the logical successors to books. http://tc.eserver.org/29375.html http://tc.eserver.org/29375.html Known to write a script or two to automate repetitive tasks like help builds, she also likes to write posts about XML-based information models like Darwin Information Typing Architecture (DITA). She often experiments with online help technology, enjoys writing blog entries, and wants to find new ways to use communication to help people understand technical solutions to complex problems. http://tc.eserver.org/29166.html http://tc.eserver.org/29166.html A comparative evaluation of two user guides,--the document traditionally used by a company and a model document designed on the basis of research results and recommendations,--was carried out using a number of complementary approaches focusing on the user. The quality and suitability of these documents for the target audience were assessed in terms of content, structure, presence of certain organizational devices (such as headings) and pictures included. The results revealed that the model document was more attractive, more efficient, and better adapted to users' needs, thanks to its modular organization (being structured according to "functions"), a large number of pictures, the presence of headings, and rationalization of the vocabulary used. http://tc.eserver.org/29116.html http://tc.eserver.org/29116.html A significant problem in technical communication is persuading the user that the information is accurate, valid, and useful. All too often, technical communicators treat users as members of their own culture. When authors do consider cultural issues, they often focus on matters such as vocabulary, visuals, and organization. Other strategies, however, can be useful in gaining acceptance of technical information in cross-cultural situations. For example, the communication theory of compliance-gaining offers suggestions for how the technical communicators can adapt the text to enhance user acceptance when communicating to members of their own culture as well as when communicating across cultures. Communicators can use promises, threats, demonstrate positive and negative outcomes, extend friendliness, etc., to develop the text. In this article, I will explain several compliance-gaining strategies authors can use, identify rhetorical strategies they can combine with compliance-gaining strategies, show how these strategies can be effective in a cross-cultural environment by comparing the strategies in two sample cultures, and analyze a brief sample. http://tc.eserver.org/28941.html http://tc.eserver.org/28941.html Documentation isn't the most fun part of design and IA, but does it have to be the most painful? Samantha Bailey looks at a tool that may help. http://tc.eserver.org/28795.html http://tc.eserver.org/28795.html 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. http://tc.eserver.org/28764.html http://tc.eserver.org/28764.html Discusses a number of trends in the technical writing world, particularly the need to make help more human by adopting conversational tones and addressing the angry/frantic state of the user. http://tc.eserver.org/28734.html http://tc.eserver.org/28734.html Documenting networks is playing less with words, and more with diagrams. It also requires an engineering mind, an ability to think out-of-box, and creative mind. Technical writers can rise to a new scale and expand their skill sets if they are able to document networks. http://tc.eserver.org/28686.html http://tc.eserver.org/28686.html Here are some 'truths' we've all heard: 'Documentation is just a band-aid for poor design.' 'Real users don't read manuals.' 'Super users never read anything.' 'Help doesn't.' But are they really true? I've seen some signs of life in the use of documentation for digital products recently. http://tc.eserver.org/28553.html http://tc.eserver.org/28553.html Braun Corporation's home-grown documentation processes served the organization well for its first 50 years as it grew from a local to a nationally-competitive producer of mobility and accessibility products. Now poised to become a global leader in its field, this corporation found its efforts hampered by ineffective and outdated documentation practices, which were hurting the company's competitive advantage. This article describes Braun Corporation's curious mixture of global reach and local isolation. By bringing in a technical communicator with expertise in user-centered design, Braun has begun reforming its formerly exhaustive documentation and communication practices. While technical communicators have incorporated a variety of strategies to develop user-centered and task-based documentation, less attention has been placed on changing the cultures of these organizations. The case presented here represents a shift from establishing documentation procedures to critically assessing and reforming existing procedures for the global workplace, describing the shift from ineffective and exhaustive processes to effective processes with defined goals and measurable outcomes. The article concludes with an inventory for determining whether other organizations are over-documenting processes and products, and offers suggestions for creating better documentation procedures. http://tc.eserver.org/28370.html http://tc.eserver.org/28370.html Interested in making the transition from software documentation to e-learning? Read about some steps that will help you ease the switch and make the most of your new opportunity. http://tc.eserver.org/28316.html http://tc.eserver.org/28316.html Documentation is a crucial component of successful product planning and implementation, so it's important that it communicates as effectively as possible. Good organization, complete information, and clear writing are, of course, key to the success of any design document, but there are some other, less-obvious techniques you can use to make your documents more readable and understandable. Here are a few of them. http://tc.eserver.org/28228.html http://tc.eserver.org/28228.html This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference in October, 2006. Every now and then, there is a change in the value of what technical authors deliver. These are moments when organisations pay attention to technical documentation. This is because they recognise that these changes mean they can create something that will be of real value to the business and to their customers. In recent years, there have been three "waves of interestingness". The first wave was the introduction of Windows Help (WinHelp). The second major wave was the introduction of the Internet and intranets. This was a time when organisations looked at how they could transfer large amounts of information from paper to online. They were faced with issues such as how users could access and understand all this information easily - issues that technical communicators deal with on a day-to-day basis. I believe we're just about to approach the new wave, which we have called "Tech Writing 2.0". http://tc.eserver.org/28185.html http://tc.eserver.org/28185.html Implementing structured authoring with XML allows organizations to create better content. The addition of hierarchy and metadata to content improves reuse and content management. These benefits, however, must be weighed against the time and money required to implement a structured authoring approach. The business case is compelling for larger writing organizations; they will be the first to adopt structured authoring. Over time, improvements in available tools will reduce the cost of implementing structured authoring and make it affordable for smaller organizations. http://tc.eserver.org/28186.html http://tc.eserver.org/28186.html In a structured authoring environment, authors create documents by assembling elements and text in an order permitted by the structure definition document. You might think of structured authoring as being similar to template-based authoring with a strict template. Authors do not assign formatting; the formatting is automatically assigned based on the structure of the document. Formatting may differ for different output media. http://tc.eserver.org/28177.html http://tc.eserver.org/28177.html Not every content-creation group will benefit from structured authoring and XML. Sometimes, the expense of implementation outweighs the benefits realized, especially in smaller groups with less total page count. http://tc.eserver.org/27704.html http://tc.eserver.org/27704.html 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. http://tc.eserver.org/27658.html http://tc.eserver.org/27658.html 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. http://tc.eserver.org/27654.html http://tc.eserver.org/27654.html It's often easy to identify what kinds of error messages don't help users, but it can be tricky to avoid them, and even more of a challenge to create the opposite: error messages that give users a clear indication of the problem, offer information to help them fix it, and provide tips on how to avoid the same situation in the future. This paper details the steps involved in creating understandable, helpful error messages, and suggests ways of communicating the value of good error messages to managers and executives. http://tc.eserver.org/26733.html http://tc.eserver.org/26733.html The intent of Sarbanes-Oxley (SOX) can be characterized as risk reduction: reduce errors, inhibit fraud, and provide shareholders with transparent equal-access to material knowledge. But implementation is principally procedural controls and documentation, under threat of penalty. The vague parts of SOX are where the real leverage lies: principles of intent, and corporate transparency. http://tc.eserver.org/26466.html http://tc.eserver.org/26466.html Information Layering is not new, but it has acquired a new dimension through modern technical and interactive possibilities. Even as of now, this technique can be used to make HTML-help considerably more user friendly. http://tc.eserver.org/26226.html http://tc.eserver.org/26226.html What is a knowledge base? What are the components necessary to build one? http://tc.eserver.org/25619.html http://tc.eserver.org/25619.html Good organization, complete information, and clear writing are, of course, key to the success of any design document, but there are some other, less-obvious techniques you can use to make your documents more readable and understandable. Here are a few of them. http://tc.eserver.org/25379.html http://tc.eserver.org/25379.html As technical communicators, we are being challenged with how to structure information in a multiple dimensional space made possible with Web technology. http://tc.eserver.org/25182.html http://tc.eserver.org/25182.html InfoSourcing's Persona based documentation approach allows our technical writers to prioritize their writing tasks and document the product to end users, who is going to use the product ..." http://tc.eserver.org/25076.html http://tc.eserver.org/25076.html Documentation and information organization are an integral part of video game construction. The video game industry may be one of the directions technical communicators will move toward in the near future. http://tc.eserver.org/25057.html http://tc.eserver.org/25057.html The Documentation Development Department (DDD) of Hitachi has been improving manuals by collecting, classifying, and analyzing inquiries from its customers to the Hitachi Customer Answer (HCA) Center. The HCA Center is a telephone inquiry center established to give quick and clear answers to inquiries from customers who use Hitachi computers. http://tc.eserver.org/24884.html http://tc.eserver.org/24884.html User empowerment offers a strategy for addressing the software end user's needs. The definition of user empowerment emphasizes a user-driven, informationmanagement oriented approach in response to changes that have taken place in the modern workplace after computers and computer software arrived. Working with software requires a significant shift in thinking and learning, responding to increased abstraction, isolation, and information volumes. Computermediated work demands that users develop new skills and job roles, and that documentation writers develop new techniques for manuals. http://tc.eserver.org/24850.html http://tc.eserver.org/24850.html All too often, developers think that documenting their new creations just means writing a detailed technical description of what it does. In a sense, they're explaining things to themselves. But what you really need to do is explain things to someone who's coming across your stuff for the first time. http://tc.eserver.org/24784.html http://tc.eserver.org/24784.html Research shows that adults learn more efficiently when they have formed an accurate mental model of the product they are trying to use. We can help our users form accurate mental models more quickly by graphically depicting that model on the interface. One product using that approach allowed engineers to become productive with no reference to user documentation. http://tc.eserver.org/24641.html http://tc.eserver.org/24641.html Searching for the right tool for your instructional design needs? Learn about your options through capsule reviews of instructional simulation programs and full-service authoring tools. http://tc.eserver.org/24606.html http://tc.eserver.org/24606.html The sensation-perception continuum represents the interplay of sensation and perception in everything we think and do. Technical communicators must exploit this continuum by understanding and applying sensory filters and perceptual tendencies in the design and development of information. This paper discuss three sensory filters: thresholds, cocktail-party effect, and sensory adaptation; it discusses four perceptual tendencies: perceptual set, figure-ground relationships, laws of grouping, and goodness of figures. http://tc.eserver.org/24572.html http://tc.eserver.org/24572.html This article shows how user-centered design can be applied to documentation and reports the results of a two-year contextual design study. The article (1) demonstrates how contextualdesign can be applied to information and (2) reports some of the study's results,outlining key insights gleaned about users. The study found that users vary widely intheir information needs and preferences. Users employ a variety of learning strategies inlearning new software and in overcoming problems encountered within applications.Documentation can better meet variances in learning styles and user preferences whentightly integrated into applications, accessible in the user's own language. Additionally,documentation is most beneficial when several assistance options exist for users tochoose among, varying according to context, task, and user need. Finally, the article discussesthe constraints that affect the implementation of design ideas and explores implicationsfor practice and additional research. http://tc.eserver.org/24422.html http://tc.eserver.org/24422.html Effective technical manuals and training meet the needs of the customer. No one will argue with that statement. But the trick is to identify the needs of the customer. This paper describes one method to focus product information development on the customer: the needs analysis survey. This methodology that is common in course development and training identifies the tasks customers perform. It also allows course developers and technical communicators to collaborate on an area that they both understand. http://tc.eserver.org/24353.html http://tc.eserver.org/24353.html Only a small percentage of users open Help, and they usually do that only when they have trouble with the application. One way to reach a broader audience is to integrate assistance into the user interface so that people understand the product as they use it. This paper describes our reasons for moving in this direction, provides examples of integrated user assistance, and discusses issues and concerns inherent in moving away from traditional Help. http://tc.eserver.org/24330.html http://tc.eserver.org/24330.html In an undertaking such as the metamorphosis from printed instructions to on-line instructions, it is important to have a process in place. Relying on the process used by the User Interface Design Department at Thomson Consumer Electronics has helped my department remain focused and on schedule with the project. This paper briefly outlines the Consumer Information Design Department’s process for creating an interactive instruction manual prototype, and might serve as a guideline for others who may also be making the leap from paper to interactivity. http://tc.eserver.org/24160.html http://tc.eserver.org/24160.html None of the previous studies on screen captures addressed the functions in the framework. There was no empirical research on any of the four functions of screen captures. This article presents our research on these functions. Each section starts with a brief explanation of the function. Next, we illustrate the screen capture designs used to test the function. The remainder of each section explains the setup and results of the empirical study. The article ends with some general conclusions about the functions of screen captures. http://tc.eserver.org/23781.html http://tc.eserver.org/23781.html Test subjects were asked to match body images shown from varying points of view. Their preference was for images that placed critical distances across the display plane; their error patterns suggest that several variables interact to affect the accuracy of perceiving body positions in illustrations. http://tc.eserver.org/23698.html http://tc.eserver.org/23698.html The experience of setting up a new home theater system also sharply reminded me of what it is like to look at something as a new user: staring at a bunch of knobs and holes for the first time, holding a tassel of wire in one hand and a manual in the other, and really just wanting the darn piece of ?%^%! to do what it's supposed to do. http://tc.eserver.org/23576.html http://tc.eserver.org/23576.html This presentation addresses designers and documenters who develop technologies for human use. The content is based on an intensive 42-hour training package, developed by Communications and Training Inc. Course content and duration can be modified to meet individual requirements. One day interactive workshops are also available. http://tc.eserver.org/23492.html http://tc.eserver.org/23492.html How to produce screenshots which include the mouse-pointer. http://tc.eserver.org/23406.html http://tc.eserver.org/23406.html This article deals, despite the title above, with aspects on handling and checking of technical documentation. I consider these aspects as part of the functionality of documentation besides more conventional functionality such as factual correctness, layout, combination of figures and text. http://tc.eserver.org/23389.html http://tc.eserver.org/23389.html The current trend among technical communicators is a twisted form of minimalism that says the documentation should contain procedural documentation but little or no reference documentation. I believe that this trend is a disservice to our customers and tends to increase technical support costs because customers subjected to this form of documentation have little or no access to the information they need. If it’s not there, they can't find it. http://tc.eserver.org/23399.html http://tc.eserver.org/23399.html 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. http://tc.eserver.org/23409.html http://tc.eserver.org/23409.html 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. http://tc.eserver.org/23430.html http://tc.eserver.org/23430.html Nobody reads user manuals for pleasure. And yet we all make our living from them, and hope that what we produce is at least useful, if not actually enjoyable http://tc.eserver.org/23289.html http://tc.eserver.org/23289.html What can manufacturers do to improve the readability of manuals that accompany juvenile products? http://tc.eserver.org/23288.html http://tc.eserver.org/23288.html According to the Consumer Electronics Association, product returns represent a $10 billion-dollar-a-year problem for the consumer electronics industry. Technical support costs are spiraling (even with the migration to off-shore providers) while consumer satisfaction with this support is plummeting. New technology and expanded offerings to a stabilized market are increasing competition. What can manufacturers do to help combat these problems? Better consumer manuals are a start. http://tc.eserver.org/23264.html http://tc.eserver.org/23264.html Turning 'help' systems and 'browsers' into robust structured-document viewers: the DocBrowser. http://tc.eserver.org/23216.html http://tc.eserver.org/23216.html This interview focuses on Jesse James Garret's Visual Vocabulary, a site architecture documentation standard. http://tc.eserver.org/23141.html http://tc.eserver.org/23141.html The user's idea of the problem is often very different than the help or program designer's. The online help topics often reflect the designer's viewpoint, not the user's. http://tc.eserver.org/23118.html http://tc.eserver.org/23118.html An increasingly popular component of modern graphical human-computer interfaces are graphical command buttons. Studies have shown that graphical command buttons can enhance user productivity. However, two factors, the time required to acquire a working knowledge of the graphical command set and the need for frequent use to maintain the knowledge limit the effectiveness of graphical command buttons as a user interface strategy. This study attempts to quantify the effects of four types of help (balloon style, a mouse documentation line at the bottom of the screen, a help browser, and hardcopy documentation) on the ability of novice users to acquire a working knowledge of a graphical command set. The study did not find any significant difference (based on the anova and manova tests) between the four treatments. http://tc.eserver.org/22878.html http://tc.eserver.org/22878.html Today's documentation must be designed with information retrieval as its key objective. When information is organized and mapped into a consistent, logical structure that uses retrievability aids such as labels that facilitate scanning, blocks of information, advance organizers for the information, keywords, meaningful indexes, and a hierarchical organization, readers can quickly locate and use the information that they need. http://tc.eserver.org/22651.html http://tc.eserver.org/22651.html Your product is almost ready for release. You're about to pat yourself on the back when you realize that you have no user documentation! Panic sets in. http://tc.eserver.org/22466.html http://tc.eserver.org/22466.html 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. http://tc.eserver.org/22160.html http://tc.eserver.org/22160.html Nearly 20 years ago, the profession of technical communication began to focus on developing task-oriented documentation. Although task-oriented documentation has always been produced, particularly for consumer products, it was not the standard in the computer industry. More often, people writing about computer systems focused on the system rather than on the tasks people needed to perform. Systems-oriented documentation was the norm. http://tc.eserver.org/22161.html http://tc.eserver.org/22161.html Redesign your information; write topics, not books. http://tc.eserver.org/22144.html http://tc.eserver.org/22144.html 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. http://tc.eserver.org/21979.html http://tc.eserver.org/21979.html Technical publications departments in their infancy seem to have great difficulty producing documentation that is well designed and consistent in appearance throughout all documents. As the department matures, it attempts to "consistify" the appearance of the documentation, but, unless there is an experienced template designer on board, this is often a drawn-out process involving focus groups and much squabbling. Once the design is complete, however, it tends to be nearly identical to the templates designed by every other technical publications department in the world. Aside from a handful of design features that distinguish the look and feel of one company's documentation from that of its competitors, everything else is pretty much the same. Whether the focus group spends six months or two years designing templates, they all discover that a well-designed user guide contains some specific and standard design elements. http://tc.eserver.org/21709.html http://tc.eserver.org/21709.html XML provides a robust, non-proprietary, and verifiable file format for the storage and transmission of text and data both on and off the Web. XML removes the complexity of SGML, making it easier to define your own document types, and to write programs to handle them. http://tc.eserver.org/21657.html http://tc.eserver.org/21657.html The issue of documenting schemas—or any machine readable language—goes beyond simple additions of comments. Thereal challengeistocreateschemasthat arereadablebothdirectlybylookingat their sourcecodeandbydocumentation extraction tools. http://tc.eserver.org/21564.html http://tc.eserver.org/21564.html When I worked for a large insurance company, my team as tasked with re-designing the customer service area for a external Web site that supports annuities and mutual fund customers. I proposed redesigning the entire site including an actual help system (like with ones you can create with RoboHelp) to reduce customer service support calls. I was really surprised that everyone thought this was such a novel idea -- I thought it made perfect sense. Then, it hit me -- you don't see a lot of help systems for Web sites. http://tc.eserver.org/21494.html http://tc.eserver.org/21494.html A compilation of the most frequently asked questions about graphics in electronic catalogs. You will find answers to general as well as to technical questions. http://tc.eserver.org/21435.html http://tc.eserver.org/21435.html Benutzerinstruktion muß sein. In Form von Online-Documentation ist sie unmittelbarer Teil des Programms. http://tc.eserver.org/21027.html http://tc.eserver.org/21027.html In 1993, Compaq Computer Corporation ventured into a totally different market--the consumer market. Once known primarily as a company that manufactured high quality, expensive business computers through its elaborate dealer network, Compaq was faced with selling its units to consumers through retail outlets. As a result, the PC Marketing Communications department concluded that its current documentation set was not giving the students; retirees; homemakers; and small business owners, who work out of their home offices, the kind of information they needed to be productive. This led the department to the challenge of creating a new documentation set that would meet the needs of these new customers. http://tc.eserver.org/21023.html http://tc.eserver.org/21023.html Often in the computer industry there is a tendency to provide information about the features of a system. However, customers usually purchase the system based on knowledge of its features, when they receive the product they need information on how to accomplish tasks. Developing task-oriented information requires a shift in perspective from what the computer technology can do, to what your customers want to do with the technology. The resulting information must be usercentered rather than feature-driven. These types of customer requirements demand afresh development approach. http://tc.eserver.org/20725.html http://tc.eserver.org/20725.html Technical communication's long-time focus on task-oriented documentation has left customers with too many tasks and too much information; itï¿Âs time for a new approach. A user-centered approach reflecting a thorough understanding of users and how they engage the product is the surest route to effective documentation and training. To understand what users need, we need to get closer to them by spending time in their workplaces, watching them execute everyday tasks, and listening to them. Through this kind of ethnographic activity, we will become user experts, gaining credibility within our own organizations and our user communities. http://tc.eserver.org/20727.html http://tc.eserver.org/20727.html Rockwell Software is a $90-million company specializing in plant automation software. Offices in West Allis, Wisconsin, and Mayfield Village, Ohio allow technical communicators to work closely with development teams to design, test, and release usable, consistent software and information products. While Rockwell Software’s information development process is a multi-faceted endeavor, this paper focuses on the following three steps we implement to create our information products: interviewing customers to establish information guidelines, conducting usability tests, and writing Getting Results guides. http://tc.eserver.org/20552.html http://tc.eserver.org/20552.html The user-centered design of documentation is an aspect of product design that has often been under-emphasized. Difficulties inherent in documentation design include obtaining user, feedback to high-level design objectives; extracting user. feedback specific to a product’s documentation. rather than to the product as a whole; and managing the various resource constraints inherent in product development. IBM User-Centered Design offers a solution to these difficulties by employing a set of user feedback methodologies from which the documentation designer, a member of a multidisciplinary design team, extracts pertinent data to set design objectives and follow through to low-level designs. http://tc.eserver.org/20551.html http://tc.eserver.org/20551.html Technical communicators around the world are turning to the World Wide Web us their primary delivery agent for on-line documentation. The transition from older forms of on-line documentation to HTML-based documents pre - sents new challenges in every phase of the documentation process: document creation, layout, access, and especially hypermedia capability The constant development of new web tools presents an even greater challenge for an organization seeking to stay abreast of technology with an ever decreasing budget. This panel will outline the basic steps in migrating to the web while focusing on one organization’s solution to meeting the challenges of restructuring its on-line documentation for web migration. http://tc.eserver.org/20364.html http://tc.eserver.org/20364.html This paper questions the ubiquitous practice of supplying minimalist information to users, of making that information functional only, of assuming that the Shannon-Weaver communication model should govern online systems, and of ignoring the social implications of such a stance. Help systems that provide fast, temporary solutions without providing any background information lead to the danger of users completing tasks that they do not understand at all. (Word will help us write a legal pleading, even if we have no idea what one is.) As a result, we have help systems that attempt to be invisible and to provide tool instruction but not conceptual instruction. Such a system presents itself as a neutral tool, but it is actually an incomplete environment, denying both the complexity and alternative (and possibly improved) modes of thinking about the subject at hand.