What is Documentation Architecture and What Does a Documentation Architect Do?

Prior to working with DITA XML, I worked as an Information Architect for the various professional Web sites. (I still teach a couple of courses on this subject at the University of Toronto’s Professional Learning Centre). I was intrigued with the idea of applying the same skills and techniques that I had learned from the Web to documents, having started my career as a Technical Writer in the early 90s prior to the advent of the Web. (I was also intrigued with the idea of steady paycheque too, but that’s another story…)

“Documentation Architecture” is not (yet) a common term – a Google search brings up pages relating to how to document software architecture. What I mean by it is the way that Information Architecture principles that have been applied to the Web can be used to improve sets of documentation, while keeping in mind the differences between the Web and the many types and formats that documentation takes. In the same way that anyone who practices Information Architecture is considered to be an Information Architect (IA), anyone who puts the core IA-ideas into practice specifically for documentation formats is a Documentation Architect (DA).

For those of you who aren’t familiar with Information Architecture, there are plenty of definitions of Information Architecture out there, but my favourite is from Louis Rosenfeld and Peter Morville’s “Information Architecture for the World Wide Web” (better known in IA circles as the “Polar Bear book” for its distinctive cover) where they say that an Information Architect is someone who:

Clarifies the mission and vision for the site, balancing the needs of its sponsoring organization and the needs of its audiences.

Determines what content and functionality the site will contain.

Specifies how users will find information in the site by defining its organization, navigation, labeling, and searching systems.

Maps out how the site will accommodate change and growth over time.

Replace the word “site” with “document” and you get an idea of what I am talking about – the same principles apply to the DA’s outlook on approaching a set of documentation.

The DA needs to take a holistic approach to tackling documentation: one type of doc is typically one of several different types out there, each with their own focus and different audience. The type of person who will be reading a “Quick Start” guide is different that someone who will sit down and read a user’s manual, and you need to take that into account when re-architecting these document types. While you have different audiences for different document types, the DA needs to survey and audit all of the different document types that are available to ensure that they all have a common sense of purpose, and that they contain the right type of content for their intended audience. The DA also needs to ask questions of the document stakeholders as to whether it makes sense for certain doc types need to exist (“why have a specification pamphlet for users which is separate from the user’s manual?”) and also to look for “holes” where there are obvious documentation opportunities which are missing (“why don’t we have a Quick Start guide for our more experienced users?”).

Through the process of a content audit the DA can also determine what content ought to be in a document set, always with an eye to finding similar content already available in other documents with the intent of modularizing that content for reuse between those document sets. The best way of ensuring high reuse rates for content is to build it into the documentation sets, so that information from one set of docs cascades through subsequent docs related to it.

When it comes to functionality, the DA needs to consider the optimal way for arranging everything from the sub-heading levels to use in a Table of Contents to the order for efficient Indexing from the user’s perspective. Depending on the type of “document”, this can also be extended to any interactive elements that are increasingly coming into play (everything from interactive quizzes, polls, embedded video and 3D visualizations). The DA also ensures that the labels (think: headers or metadata) are clear from a user’s perspective. Clarity always wins out over hype, and whenever possible avoid parroting the marketing definition of a product’s feature and instead focus on what it actual does and how it does it, which as few buzzwords as possible.

Finally, the DA also need to think about the life cycle of a document, not just as it relates to a given product, but as to how the document itself may evolve over time. For example, a dozen years ago it may have been sufficient to deliver a compiled help file to go with a piece of software but now there are all sorts of other options available, including Web-based help, local browser-based help, embedded multimedia tutorials, and so on. It is also a good idea to think about localization issues from the beginning, as things get very expensive very quickly if you have to retroactively bolt-on a localization infrastructure to an existing documentation set. There are also times when a type of document is no longer needed, either because the product it is tied to goes away, or it has been superseded by some other set of documents. There are additional challenges specific to when a document type is “sunset”, such as negotiating how long support and updates to it can be expected to be grandfathered.

In short, the Documentation Architect is an Information Architect who focuses on non-Web publications, optimizing them for use by readers by applying IA principles to them. Businesses need them because they can help make much the “pain” associated with an existing documentation set go away, can help optimize the transfer of information into a Content Management System (CMS), and also to find productivity savings through content reuse. If you have a medium-to-large documentation set and you don’t have a DA managing it, your publications will inevitably cost more than they have to.