Every documentation tool has a built in information design bias. When you choose a tool, be it FrameMaker, DITA, AuthorIt, a WIKI, or SPFE, you are implicitly choosing an approach to information design. If you don’t understand and accept the design implications of your tool choice, as many people do not, you are setting yourself up for expense, frustration, and disappointment.
I suspect that most of us underestimate how much our tools affect our design. Design is always a matter of balancing the desirable with the practical. Want a car the can pull 1G in the corners, do zero to 60 in 4 seconds, gets 60 mpg, and can carry 12 passengers in comfort? Well, you can’t have one. As desirable as all these characteristics might be, we don’t have the tools to build something that fulfills them all. We bend our design to the capability of our tools.
Since most tech pubs folk have been using Desktop Publishing and/or Word Processing tools for the last 25 years, they have naturally, if tacitly, adapted their information design and their presentation and formatting design, to the strengths and weaknesses of those tools. We have been doing this for so long that we seldom recognize or think about the constraints as being imposed by the tool anymore, we simply design with a tacit understanding of what kinds of designs are feasible to execute and which are not.
We seldom recognize, therefore, how much our accustomed tools have influenced our design philosophy. It no longer appears to us as an adaptation to the limits of tools, but simply as an established best practice in design.
When we move to a new tool, therefore, we often expect to keep the same information design and the same presentation and formatting style as we had with the old tool. In many cases, maintenance of the current design is written into the business requirements that we take to market when we purchase a new system.
Herein lies much of the grief, anguish, and expense that so many companies experience when they switch tools.
I was talking the other day to a career tech writer who I have known for many years. The company he works for has adopted DITA, but is refusing to adopt their information design to the DITA model, which is causing him much frustration. The company refuses to use DITA conventions such as the short description element in the way that they were intended to be used because, they say, that is not the way they do things. Yet if you don’t do things the DITA way, you have to expend a lot of effort to make DITA behave differently.
Many people adopt DITA because they believe the promise of reuse it offers, or because they have become convinced that XML is the future and DITA appears to provide a easy route to XML (this is something of an illusion, as the DITA package makes it look easier than it really is). They often don’t realize that DITA has some very specific information design principles build into its DNA. (Not everyone misses this, of course; some people adopt DITA specifically because they like these principles).
Two major factors influenced the design DNA of DITA. One is Horn’s information mapping, of which DITA implements a simplified variant, and the fact that DITA was originally created to develop online help systems. The result is that DITA strongly favors the kind of information design that I have dubbed Frankenbooks: deeply nested hierarchies of topics which may or may not make sense independently of the parent and sibling topics in which they are embedded.
By now it is possible to recognize the DITA look in a doc set. The surest sign is the brief topics, sparsely linked, with links at the bottom pointing you to the previous, next, and parent topics. Frankenbooks are in DITA’s DNA.
Similarly, many people choose wikis because of their ease of use, and their ability to greatly expand the number of people who can contribute to the documentation set. But wikis have an information design bias in their DNA as well. Wikis favor Every Page is Page One topics; topics that are self sufficient, stand alone, and richly linked to related topics, but without any sense of next, previous, or parent. Every Page is Page One is in wiki DNA (and SPFE DNA) the way long documents are in Frame’s DNA, and Frankenbooks are in DITA’s DNA.
Of course, this does not mean that you cannot reproduce your existing design in any of these tools. You could write books in a wiki or Every Page is Page One topics in Frame. But you will be fighting the tool every step of the way.
Worse, in attempting to force your old design principles on the new tool, you may compromise its effectiveness and lose much of the efficiency you originally bought it for. This is important to understand, because the design principles built into the tools DNA, and the particular kinds of production efficiencies it provides, are not incidental to each other; they are intimately and inextricably tied together.
In SPFE, for instance, one of the principle production efficiencies it provides is soft linking. But soft linking works best and most naturally in an Every Page is Page One information model because that model makes it easiest to identify link targets algorithmically. Another virtue of SPFE is that it allows a wide variety of authors to contribute structured content without requiring a detailed knowledge of the publishing system. But that works much better in an Every Page is Page One information design, in which authors do not have to be aware of the context in which the topic they are writing will be used.
Wikis, similarly, open up authoring to a wide audience without requiring much knowledge of the wiki system, but you give much of that up if you try to use the wiki to write a book. DITA uses its information types and maps as the underpinning of its reuse model. You can force DITA to create a traditional narrative flow or a set of Every Page is Page One topics, but both will make the reuse mechanism harder to use.
Each tool, then, should be looked at holistically. All the process efficiencies and design possibilities that each tool offers are a package, and you will cause yourself much grief and expense if you try to mix and match. While all these tools allow for a great deal of design flexibility within the overall design philosophy that is built into their DNA, none of them work well when your design forces them outside that envelope. Despite what sales folk may say to begile you, none of them offer exactly what you are doing now, only better. A change of tool demands a change in design. Something is gained, and something is lost.
This is by no means easy to deal with, of course. Our design skills have been honed over the years in one kind of tool environment. Put a different kind of tool in front of us, and all our design instincts are suddenly at odds with the tool. Every design choice then becomes a focrefully act of breaking the old mold and deliberately probing and testing the limits and possibilities of the new tool and figuring out how to create a design that takes full advantage of the possibilities and is affected as little as possible by the limits.
This will be emotionally hard, as well as intellectually hard, because it will mean giving up some things you have come to value highly over the many years of your professional practice. JoAnn Hackos recently pointed out an article that argues that fear of change can best be understood as fear of loss. Changing your information tools will mean losing some things you have been used to. It will also mean gaining some new things that you want, and presumably, if you have done your homework properly, the value of what is gained will outweigh the value of what is lost. But if fear of loss causes you to cling desperately to the things you should be letting go, you will certainly increase your costs, and you will probably lose some or all of the new things you hoped for. You could end up doing the same thing you were doing before but with tools less well suited for the job.
There is another pitfall to be aware of as well. The almost universal advice to people contemplating a move to any form of structured writing is to begin by modeling your content. This is good advice in many ways. The last thing you should do is rush out and buy a tool, then try to figure out what to do with it. You need absolutely to start with your business goals and your information designs.
But if you create your information models and your information designs without looking at the tools and at the design patterns that exist in their DNA, your information models and designs will actually be based on your existing design patterns — the ones that you absorbed over the years from your old tools. If you then build those models and designs into your requirements for a new system, you will, in fact, have produced a recipe for frustration, disappointment, and cost overruns.
The only way out of this is to step back and think about the different design patterns that exist for your type of content: Narrative books, Frankenbooks, Every Page is Page One, etc. Understand them all, their strengths and their weaknesses, and what the differences between them will mean for your readers, then look at what you will need to do to move your content from its current design pattern to the new design pattern you have chosen, and what kind of development process will be most effective for you to produce content in the chosen design pattern.
Only when this is done are you ready to proceed either to the details of design or the details of tool selection.