Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Topic-based authoring vs. Modular authoring

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.
Why should this post be closed?

This post was sourced from https://writers.stackexchange.com/q/37891. It is licensed under CC BY-SA 3.0.

0 comment threads

2 answers

You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.

+0
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

0 comment threads

+1
−0

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.

History
Why does this post require moderator attention?
You might want to add some details to your flag.

This post was sourced from https://writers.stackexchange.com/a/37898. It is licensed under CC BY-SA 3.0.

0 comment threads

Sign up to answer this question »