Tag Archives: Tom Johnson

DocBook resurgent: what it tells us about structured writing and component content management

A new XML-based content management system that is not based on DITA. Bet you didn’t see that coming. But I think it tells us something interesting about the two sides of structured writing. Tom Johnson’s recent sponsored post explains the origins of Paligo, a relatively new CCMS out of Sweden. Paligo was developed by a company… Read More »

Writing Excellence Through Domain Awareness

A little while back, Tom Johnson posted an article entitled Seeing things from the perspective of a learner in which he says, “The balance between knowing and not knowing is the tension that undergirds the whole profession of technical writing.”. I think that is absolutely correct. The point, after all, is to assist the reader on their… Read More »

Subject First; Context Afterward

In communication, they say, context is everything. Actually, “everything” consists of context and subject. Useful information is subject in context. The question is, which comes first: context or subject? In the book era, the content search pattern was: context first, subject afterwards. That is, suppose you deliver three different products and have released three different versions of… Read More »

Structured Writing is Essential for Developer Docs

Tom Johnson wrote a post recently in which he questioned the value of structured writing for developer documentation. Needless to say, I disagree. But Tom and I are not really at odds here. Rather, he means something different by “structured writing” than I do. Structured writing is about content quality, not publishing What I mean… Read More »

Passive vs. imperative linking

Summary: Writers worry about whether links will distract users. To discuss this concern, we need to begin by distinguishing between imperative links that command the reader to click and passive links that merely make finding ancillary material easier. Tom Johnson wrote a post recently in which he raised an important question about linking, and referred… Read More »

Structured Writing FOR the Web

Tom Johnson started the discussion with  Structured authoring versus the web. Sarah O’Keefe and Alan Pringle took it up in Structured authoring AND the Web. My turn: Structured authoring FOR the Web. One of my long term grievances is that structured authoring has been adopted piecemeal. Rather than approaching it holistically as a method that can provide a wide… Read More »