8

What is the difference between "topic-based authoring" and "modular authoring"?

As I know, there are two well-known authoring approaches:

  • Narrative authoring;
  • Topic-based authoring (see link above).

Narrative authoring is the most simple concept - just open your text editor and write entire text, from start to end. This is how writers worked for thousands of years.

Topic-based authoring is very modern approach and popular for large technical documentation projects. DITA, Scrivener, MadCap Flare are all about it. The main goal of topic-based approach is the content reuse.

Now, as I read yesterday, there is another, third approach - modular authoring. It is described here:

https://www.pdsvision.se/blog/xml-dita-docbook-s1000d-shipdex-confused/

But what is the actual difference between modular and topic-based approaches? I don't understand it.

11

This is a complex question -- complicated 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 and out of different information sources driven by their immediate tasks. Carroll developed a theory of information design called minimalism. Among other things, this theory called on authors to create smaller units of information, to design each unit with the expectation that users would access it at random, and to focus 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 theory corroborated Carroll's findings. (https://www.nngroup.com/articles/information-scent/)

The Web greatly enhances people's information foraging and changes the way people work and learn. Stack Overflow is a prime example of this trend. It increases the importance of creating small independent topics, which my book calls "Every Page is Page One" (EPPO) topics. It also diminishes the priority of creating textbook-style technical manuals. This approach is one meaning of "topic-based" writing, and it merely 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. However, in DITA, a document is a map of topics, not blocks. In DITA, 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 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 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 distinguish between these two forms of topic-based writing, but unfortunately, "modular writing" also gets used in these two distinct ways.

I suspect that this continued confusion is because, if you are doing topic-based writing in the Every Page is Page One sense, you are almost certainly not building your short articles from separately managed blocks. The people who are doing that are the ones who are assembling larger works. Both sets of practitioners use the same terms to describe what they are doing, but they are 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.

| improve this answer | |
  • 1
    Great answer! There are few misprints, as it looks for me, I posted them to jsFiddle: jsfiddle.net/cjgz4eqm. (I'm not native English speaker, though). – john c. j. Jul 26 '18 at 21:28
3

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.

| improve this answer | |
  • Could you add 2 examples in your answer, please? So, the first example should illustrate topic-based approach (as you see it) and the second example should illustrate modular-but-not-topic-based approach. That way the difference will be understandable from the practical point of view. Because, currently I understand your anser, but I cannot imagine how does this difference will work in real world. – john c. j. Jul 26 '18 at 16:17
  • @johnc.j. That's only one paragraph but it is two examples. – Ash Jul 26 '18 at 17:09

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.