For those of you who are not familiar with information architecture, there are many definitions of information architecture, but my favorite is the one given by Louis Rosenfeld and Peter Morville in "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 of the site, balancing the needs of its sponsoring organization and the needs of its audience. Determines the content and functionality the site will contain. Specifies how users will find information on the site by defining its organization, navigation, labeling and search systems. Describes how the site will adapt to change and growth over time.
Replace the word "site" with "document" and you will have an idea of what I am talking about - the same principles apply to the vision of the DA (documentation architect).
The DAT (technical architecture document) is a document produced by a technical architect or a documentation architect. It defines and documents everything that has to be done and put in place to carry out the architecture successfully, in order to meet the objectives and respect the various constraints.
It explains exactly which technical resources (servers, machines, networks, protocols, and so on) are needed to meet the requirements, and how they must be implemented within the information system, in order to maintain performance, stability, security, and so on.
There are several formats of DAT, ranging from a few pages with diagrams to complete, formal reports of more than 100 pages. It should be kept in mind, however, that this is a living document, designed to be consulted, commented on, reviewed and approved by the various stakeholders.
My recommendation for approaching an architecture is to divide it into coherent and complementary subsets. This is the classic engineering approach: a complex whole is divided into simpler, more manageable parts.
By default, an information system seen from the point of view of technical architecture can be broken down into 4 planes:
- The functional plane represents the business aspect, that is to say what the application does and the nature of the data it exchanges with the rest of the world;
- The application plane focuses on the software aspect: the flows (protocol, frequency, direction), the stores (data sharing, and so on), the middleware (database, java server, and so on) and the frameworks used (.NET, Java, and so on);
- The infrastructure plane describes the technical choices: the servers (in the cloud or elsewhere), their sizing, the interconnection through the networks, and so on;
- The operational layer, finally, describes how the system will be managed: the backup, monitoring and measurement mechanisms, and so on.
There are thus 4 types of architecture in every system.
- Operational architecture
- Functional architecture
- Application architecture
- Technical architecture
"Documentation architecture" is not (yet) a common term - a Google search brings up pages about how to document software architecture. What I mean by it is that the information architecture principles that have been applied to the web can also be used to improve documentation sets, while keeping in mind the differences between the web and the many types and formats that documentation takes.
The DA must take a holistic approach to documentation: a given document type is usually one among several types, each with its own purpose and its own audience. The kind of person who will read a "quick start" guide is different from the one who will sit down and read a user manual, and you have to take that into account when redesigning these document types. Although you have different audiences for different document types, the DA must review and audit all the different document types available to make sure that they all share a common sense of purpose and that they contain the right kind of content for their destination.
As regards functionality, the DA must consider the best way to organize everything, from the levels of subheadings to use in a table of contents to the order that makes indexing effective from the user point of view. Depending on the type of "document", this can also extend to all the interactive elements that increasingly come into play (from interactive quizzes and polls to embedded video and 3D visualizations). The DA also makes sure that the labels (think: headings or metadata) are clear from the user point of view. Clarity always wins over hype and, wherever possible, focus instead on what the product actually does and how it does it.
Finally, the DA must also think about the life cycle of a document, not only with regard to a given product, but also with regard to the way the document itself may change over time. For example, a dozen years ago it may have been enough to provide a compiled help file to go with a piece of software, but now there are all sorts of other options available, including web help, local browser-based help, embedded multimedia tutorials, and so on. There are also times when a document type is no longer needed, either because the product it relates to disappears, or because it has been replaced by another set of documents.
In short, the documentation architect is an information architect who focuses on publications, optimizing them for use by readers by applying the principles of information architecture to them. Companies need one because they can help remove the "pain" associated with an existing documentation set, can help optimize the transfer of information into a content management system (CMS), and can also deliver productivity savings through content reuse. If you have a medium to large documentation set and you do not have a DA managing it, your publications will inevitably cost more than they need to.
As a complement, you will find below a course by Openclassrooms under license
CC BYSA 4.0.
See you very soon!
Documents were attached to the original article ("exemple_DAT.doc", "Comprenez les objectifs et attendus d’un DAT - OpenClassrooms.pdf"): the download widget of the former editor did not carry them over into the archive, and they are not republished.