Topic-based authoring vs. Modular authoring

This is a complex question -- complex enough that I wrote a book about it: Every Page is Page One: Topic-based Writing for Technical Communication and the Web from XML Press (https://xmlpress.net/publications/eppo/).

At the heart of the confusion is ambiguity about what the word "topic" means.

For a long time, we used the word "topic" to mean a short self contained piece of information on a single subject: a help topic, for instance. A topic was a unit of consumption. A recipe is a topic. A wikipedia entry is a topic. A manpage is a topic.

Meanwhile, Robert Horn developed a theory of information mapping that claimed you could improve writing by breaking a document up into sections of one of six (originally seven) information types: Procedure, Process, Principle, Concept, Structure, and Fact. In information mapping, a document was a map consisting of blocks of different information types. This was not quite modular writing -- it was more a matter of modular design -- but it introduced the idea that a big document could be made up of smaller discrete pieces. (https://en.wikipedia.org/wiki/Information_mapping)

Around the same time, John Carroll of MIT did a series of studies on how people use information that showed that the kind of systematic technical manuals commonly written in the 80s did not work very well because people did not use them systematically. Instead, they tended to hop in an out of different information sources driven by their immediate tasks. Carroll developed a theory of information design called minimalism that called, among other things, for smaller units of information that could be accessed at random and that focussed on experimentation and error recovery rather long study sessions.

Studies at Xerox PARK then led to the theory of information foraging, which says that people look for information the way wild animals look for food -- following information scent and trying to minimize the expenditure of calories. This very much corroborated Carroll's findings. (https://www.nngroup.com/articles/information-scent/)

The Web greatly enhanced peoples ability to do information foraging, which lead to a change in the way people work and learn. Stack Overflow is a prime example of this trend. Thus the creation of small independent topics, what I call "Every Page is Page One" topics in my book, became a much higher priority, and the priority of textbook-style technical manuals correspondingly diminished. This is one meaning of "topic-based" writing, and it simply means writing short independent works rather than long integrated ones.

At the same time, the proliferation of product variation and the shortening of product release cycles left tech comm departments struggling to keep up. Thus there was an increasing interest in reusing existing content as much as possible, which led to the development and increasing adoption of DITA. DITA based its data model on information mapping, though it reduced the base set of information types from six to three: Concept, Task, and Reference. (DITA allows you to create more types via a process called specialization.)

Here's where the confusion started. While Information Mapping called these units "blocks", DITA decided to call them "topics". As with information mapping, a document in DITA is a map, but in DITA it is a map of topics. In this world, therefore, "Topic-based authoring" came to mean writing discrete reusable parts of a document in isolation. While a topic in the Every Page is Page One sense is the unit delivered to the reader, a topic in the DITA sense is the unit the writer writes and often it has to be combined with other units to make something that is useful to the reader.

For instance, in the EPPO sense, a recipe is one topic. In the DITA approach, though, a recipe is made up of one concept topic (the introduction), one reference topic (the list of ingredients) and one task topic (the preparation instructions) joined by a map. (Not every DITA practitioner would actually take it this far, but it illustrates the principle.) Thus we have two different meanings of "topic" and two different meanings of "topic-based writing".

It would be helpful in the term "modular" was used to make a distinction between these two form of topic-based writing, but unfortunately, "modular writing" also gets used in these two distinct ways.

I suspect that this continued confusion is in part due to the fact that if you are doing topic-based writing in the Every Page is Page One sense, you are almost certainly not building your short articles out of separately managed blocks. The people who are doing that are the ones who are assembling larger works. So both sets of practitioners are using the same terms to describe what they are doing, but they are really doing very different things.

I coined the term Every Page is Page One term to try to reduce the confusion, or at least to give people a way to be more specific when they use these terms.

posted over 6 years ago

CC BY-SA 4.0

Mark Baker‭

4371 reputation 12 1104 744 58

Topic-based authoring is actually a particular form of Modular authoring. Modular authoring is most common in technical works but refers to any writing practice where-in different authors are given parts of a particular project based on their expertise and ability to bring that part to fruition most effectively.

Topic-based authoring is modulation based on the topic the author is an expert in. There are other ways to modulate a writing project where-in tasks are broken down, for example, based on the different environments that need to be covered (the environment may be physical or regulatory depending on the topic) or to cover differences in the time of operation where tasks differ on different shifts.

Using an aviation manual as an example in the topic based approach authors may be asked to provide their opinions on particular operations, the loading and unloading of goods, the "proper" settings to run a given aircraft at, navigation in the event of instrument failure, etc... Alternately the work may be modulated across multiple regulatory environments with authors asked to given their written opinions on a range of topics within a particular regulatory space, such as one author covering all operational standards in the EU, another covering Russia and a third for North America.

posted over 6 years ago

CC BY-SA 3.0

Ash‭

320 reputation 9 41 62 0