Topic-oriented authoring

submited by

Style Pass

2022-01-20 14:30:08

I get asked about writing methodologies with some regularity. It often starts as a “DocBook vs. DITA” question, but it's not usually about the spelling of the names between the angle brackets. As I've said before, there's nothing about the DITA methodology that you can't do in DocBook.

Usually it's about topic-oriented writing vs. book-oriented (or what I'm going to call here “narrative”) writing. The subtext is often that the topic-oriented style is better than the narrative style. It'll come as a surprise to very few that I'm not convinced.

Recently, I was describing to a group of documentation managers, tool writers, and authors how I think these two styles differ and what appear to be their respective strengths and weaknesses. In the course of this discussion, the following analogy occurred to me.

Imagine that instead of authors, we were painters. In the narrative style, a painter (or perhaps a group of painters) begins at one side of the canvas and paints it from beginning to end (from left-to-right and top-to-bottom). They may not paint it in a strictly linear fashion, but the whole canvas (the narrative whole) is always clearly in view.