Michael Priestley

Open-source documentation: in search of user-driven, just-in-time writing

Iterative development models allow developers to respond quickly to changing user requirements, but place increasing demands on writers who must handle increasing amounts of change with ever-decreasing resources. In the software development world, one solution to this problem is open-source development: allowing the users to set requirements and priorities by actually contributing to the development of the software. This results in just-in-time software improvements that are explicitly user-driven, since they are actually developed by users.In this article we will discuss how the open source model can be extended to the development of documentation. In many open-source projects, the role of writer has remained unchanged: documentation development remains a specialized activity, owned by a single writer or group of writers, who work as best they can with key developers and frequently out-of-date specification documents. However, a potentially more rewarding approach is to open the development of the documentation to the same sort of community involvement that gives rise to the software: using forums and mailing lists as the tools for developing documentation, driven by debate and dialogue among the actual users and developers.Just as open-source development blurs the line between user and developer, open-source documentation will blur the line between reader and writer. Someone who is a novice reader in one area may be an expert author in another. Two key activities emerge for the technical writer in such a model: as gatekeeper and moderator for FAQs and formal documentation, and as literate expert user of the system they are documenting.

DITA XML: a reuse by reference architecture for technical documentation

The Darwin Information Typing Architecture is an XML architecture for producing and reusing technical information. DITA promises the following:Scalable reuse, so you can reuse content in any number of delivery contexts simultaneously without complicating the sourceDescriptive markup, so you can use markup that describes your information in terms your customers needInterchangeability, so you can treat specialized markup as if it were general, getting reuse of tools and processes defined at more general levels of descriptivenessProcess inheritance, so you can reuse existing process logic in your specialized processes.It accomplishes these goals by applying the principle of reuse by reference to the dimensions of content, design, and process within a technical communications workflow.

A unified process for software and documentation development

This paper proposes the integration of the documentation development process into the rational unified process (RUP), a formal development process for software applications. Specifically, the paper identifies (in RUP parlance) the workers in the process (such as technical writer, information architect), the artifacts required by and produced by the documentation process (including concept, task and reference documentation), and the documentation development workflow (the activities of the workers who produce the artifacts). This paper describes a documentation development process in terms of its integration points with software development processes, and also in terms of its own flow and progression as a separate process.

Task oriented or task disoriented: designing a usable help web

In complex products, there can be hundreds of tasks that require documentation. Using active verbs, and numbered lists. in brief documents will make a task easier to follow, but won’t make it easier to find. A flexible delivery mechanism, such as an online web, can potentially make task information much easier to find and understand. However, the flexibility also has its drawbacks: a poorly designed web is much less usable than a poorly designed hook..

A wizard for wizards: decision support for the new or despairing user

2. INTRODUCTION One of the perennial trade-offs in usability is between the needs of the novice and advanced user. Typically, the novice user wants a more constrained usage path with more guidance and fewer options, while the advanced user wants more flexibility, less guidance, and faster access to more options. If their usage flow were to be shown as a decision tree, then the novice user requires a tree with more depth and less breadth (more guidance, fewer options presented at any one time), while the advanced user requires a tree with less depth and more breadth (less guidance, more options instantly available).

Scenario-based and model-driven information development with XML DITA

In this paper, I describe how I followed an end-to-end development process in the development of the users guide and help information for XML DITA, using scenarios to define my information needs and maps to describe my information model. By using technology driven by maps and scenarios, I was able to keep the information focused on user goals and requirements from its inception through to its final form. The paper will also look at how an integrated end-to-end process can help keep information on track through staged delivery of content to ensure early and ongoing feedback, and will look at some future opportunities for further integration in the stages of the information development process.

Rethinking the reference manual: using database technology on the WWW to provide complete, high-volume reference information without overwhelming readers

The IBM Open Class Library Reference for VisualAge for C++ spans five thick volumes, with over 5000 pages of information. It documents the 1500 C++ classes of the Open Class Library, with all their behavior and d@ and usage notes for the five different platforms (0S/2, Windows NT/95, AIX, 0S/ 400, and MVS/ESA) on which the libraries are available. These class libraries allow application developers to use a common code base to develop native applications for multiple platforms.

Dynamically assembled documentation

As online information becomes more comprehensive in its scope, the sheer wealth of information can be overwhelming. Information needs to be both browsable and searchable, and both needs are best met with a structured information approach (such as SGML or XML). Browsing assumes a primary sequence of all information, which is unlikely to be appropriate for all readers. Searching assumes no primary sequence: information is sorted by relevance for a particular query, creating any number of ad hoc sequences as a result. However, the criteria for relevance specified in the search is unlikely to be reflected within the returned topics: they are usually still structured in a way that reflects the primary browsing path. For example, a search of API information for a description of a specific method returns a description of the entire class where it is declared, because API documentation is organized around classes, even though this particular search has nothing to do with classes. One way to resolve this tension (between linear display and multidimensional search) is with multiple documents that capture various useful ways of looking at the same information. However, the number of possible views and the growing size of information bases can make static generation of such views prohibitively expensive. The ideal solution would be a dynamically assembled document, in which the information base is so comprehensively structured that it can be meaningfully reconstructed into any number of relevant documents, whose derived structures reflect the needs of a particular reader and environment. This is a speculative paper that looks at what the interface to a dynamically assembled document might look like.

Specialization in DITA: technology, process, & policy

DITA is an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new information types and describing new information domains, allowing groups to create very specific, targeted document type definitions using a process called specialization, while at the same time reusing common output transforms and design rules.Specialization provides a way to reconcile the needs for centralized control of major architecture and design with the needs for localized control of group-specific and content-specific guidelines and controls. Specialization allows multiple definitions of content and output to coexist, related through a hierarchy of information types and transforms. This hierarchy lets general transforms know how to deal with new, specific content, and it lets specialized transforms reuse logic from the general transforms. As a result, any content can be processed by any transform, as long as both content and transform are specialization-compliant and part of the same hierarchy. You get the benefit of specific solutions, but you also get the benefit of common standards and shared resources.For some groups, specialization requires a radical move away from centralized processes into a world of negotiated possibilities that introduces many new stakeholders to the information management infrastructure. For other groups, specialization introduces centralization, and, while it provides new opportunities for sharing and reusing logic and design, it also requires new policies and procedures to bring disparate design and development activities into a cohesive, coordinated framework.Previous papers ([1],[2],[3],[4]) have described in some detail how the technology of specialization works, and how it can be implemented using off-the-shelf tools that are dependent only on base levels of W3C standards (XML 1.0, XSLT 1.0). This paper provides a brief summary of recent changes to DITA specialization, and describes their effects on processes, but concentrates primarily on policy considerations involved in the deployment of a specialization architecture.

DITA authoring

DITA 1.0 is an OASIS standard for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new information types and describing new information domains based on existing types and domains. This allows groups to create very specific, targeted document type definitions using a process called specialization, while still sharing common output transforms and design rules developed for more general types and domains.