Extreme documentation is an agile methodology for developing documentation in small to medium-sized teams in the face of vague or rapidly changing requirements.
Writing, compiling, and maintaining documentation is a necessary evil. While moving to DITA might not improve the quality of your documentation, it can streamline the process of creating and managing those documents.
Creating an XML-based Content Management System to single-source technical publications is as simple as 1 - 2 - 3. OK, maybe it isn't quite that easy, but this article discusses how it can be done.
This paper describes how user assistance can streamline deliverables and improve product design by analyzing usage patterns from server-based content. We can then base decisions about how to improve deliverables on a thorough understanding of how customers use help content to find information and solve problems. This approach enables user assistance to add more value to both our companies and our customers by creating a three-way dialog between user assistance, the customer, and the product team. It also broadens the definition of assistance to include helping to design products that people can use without the need for instructions.
Web 2.0 includes: wikis, podcasts, blogs, widgets/gadgets, social networks … and combinations of all the above. Not everyone contributes equally – Creators (18%), Critics (25%), Spectators (48%). But all are important.
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.
This article presents an approach to Help file design that focuses on creating a task-centered user experience and accommodates an iterative development strategy. This methodology allows the introduction of user assistance into early test phases--not only getting earlier validation for its accuracy, but also supporting quality assurance testing by serving as the test scripts for interactions with the user interface. This approach can also be a self-contained strategy--that is, one that allows an iterative approach to user assistance development even if the rest of product development operates on a waterfall model.
Animated demonstrations are replacing text as the vehicle for documentation, help, and training on new software systems. An animated demonstration is a demonstration of a particular feature or features by a ghost user. The demonstration executes the procedure for performing a task, on-screen, as the user passively watches. Whereas research into the effectiveness of animated demonstrations has produced mixed results, certain patterns of behavior are emerging. The current study replicates the learning advantage offered by animated demonstration and shows that retention is equal to that of a group instructed by text after a one week retention interval. Implications for development of on-line training materials are discussed.
What if online help could be configured to be context-sensitive in a different way than usual? What if, when the user launches the help system, instead of opening to some assigned help topic, it instead runs a preprogrammed search on keywords assigned to that topic?
Facing the challenges involved in developing documentation for component-based software (for example, object-oriented technology, intelligent agents, and distributed computing) requires a documentation strategy based on the same processes and methodologies used by such technologies. These strategies need to be adapted to meet documentation, rather than coding needs. Developing this strategy now, as component-based technology is still maturing, will help technical communicators keep pace.
A person usually expects another person to behave according to accepted norms, but how does a person respond to a message that violates his/her expectations? One theory dealing with violations of expectations is Burgeon and Hale's (1) nonverbal expectancy-violations theory. This theory posits that, under certain circumstances, violations of social norms and expectations may be an effective strategy for communicators to achieve the intended communication purpose. Although the expectancy-violations theory focuses on expectations for nonverbal behavior, such as gaze and conversational distance (2), I believe that this theory can also apply to expectations for humancomputer interaction.
This is a story of how one internal project at Sun Microsystems migrated printed user and reference documentation to an internal Web site. The principle architect of this site discusses how she applied object-oriented design concepts to the Web architecture to accommodate many learning styles simultaneously. As important as the successes of this project are its failures, which offer some insight into when and how to use the World Wide Web as a communication vehicle in your overall communication strategy.
Technical writers often produce documentation for products or systems without first determining the best document media or even the necessity for documentation. In some instances, alternatives to documentation may best serve the product or system users. This paper describes the field of Performance Technology and illustrates how to apply principles of Performance Technology to decide when to create documentation.
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".
This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference, in October 2006, on new trends in technical authoring. It covers the application of Web 2.0 technologies to technical documentation.
In this column, I’ll review what user assistance architects mean by reuse and what its benefits can be. I’ll then describe some different scenarios for reuse and offer guidelines that user assistance architects and information developers can follow. My examples show how DITA (Darwin Information Typing Architecture) can be an effective reuse framework. But the principles I discuss go beyond DITA, and you can apply them to any structured information framework or toolset.
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?
In recent years, an emphasis on quality has emerged in a variety of organizations and in several fields, including technical documentation. Producing Quality Technical Information (PQTI) was one of the first comprehensive discussions of the quality of documentation. An important contribution of the book is in identifying quality as multiple, measurable dimensions that can be defined and measured (previous views of quality identified it more as some elusive thing that could be identified if present but was difficult to articulate and describe). Despite its contributions to the quality discussion, PQTI runs the risk of simplifying the quality process, reducing quality to a simple checklist that information developers can use to develop effective documentation. PQTI fails to address the fluid nature of some aspects of quality: some dimensions that are important in assessing one document may be less important or irrelevant with other documents. Additionally, PQTI falls short of accounting for the larger contextual framing of documents--that the importance of individual dimensions of quality changes depending upon the audience, context, and purpose of the document.This commentary suggests that all quality efforts should be grounded in customer data and user-centered design processes, and that we should learn to better differentiate among quality dimensions, determining those dimensions that are essential to customer satisfaction and those that are merely attractive. Through increased attention to developing the quality of information, organizations can better differentiate their products and services, facilitate greater productivity, and increase customer satisfactions, all significant activities in an increasingly competitive marketplace.
Technical writers are often responsible for creating and maintaining multiple documents. In organizations where a formal editorial review is integral to the documentation process, technical writers who own multiple documents might need to address a huge volume of editorial input, often received late in the documentation cycle. What do all of those editorial comments, when taken as a whole, really mean in terms of the overall quality of the document? Lots of red ink might mean either that the document is in bad shape or that the editor loves to explain every comment, however minor, in great detail. On the other hand, a short comment buried on page 63 might turn out to be the single most important editorial value-add for the entire document!
Créée en 1963 dans le but de regrouper tous les professionnels de l'information et de la documentation, l'ADBS compte plus de 5600 adhérents et se place au premier rang européen des associations de spécialistes de l'information. Ses principaux objectifs sont de: développer les échanges entre professionnels; promouvoir et défendre la profession; diffuser et développer l'application des nouvelles technologies; contribuer au perfectionnement de ses adhérents par l'organisation de journées d'études et de sessions de formation; réaliser de nombreuses publications.
In early March we opened up the Atlassian documentation to the wider community. We added a CC-by (Creative Commons Attribution) license to our product documentation. We invited people to contribute to our documentation after signing an Atlassian Contributor License Agreement (ACLA). At that stage, the ACLA was just starting its three-month trial. The trial period has now ended, and we're delighted to say: it's a go!
Audacity is a free cross platform multi track audio editing program from Sourceforge.net. It will let you record, edit, and mix an unlimited number of tracks. Audacity runs on Windows (98 through XP), Mac OS X, and Linux.
Auditing and enforcing compliance with P&P content should not be the responsibility of a P&P group or included in the job description of a P&P practitioner. However, the charter or job description may state that P&P practitioners are responsible for supporting compliance efforts.
Since the very first Australasian Online Documentation Conference in Melbourne in 1998, the conference has developed a reputation as the premier event for technical writers, help developers, Web authors and documentation developers from Australia and New Zealand. Our speaker list reads like a Who's Who of documentation, as we strive to ensure that experts in techniques and technologies are available to share their knowledge and expertise. The conference is also a great place to network with other documentation professionals.