RE: Book on Modern Technical Writing

Subject: RE: Book on Modern Technical Writing
From: <mbaker -at- analecta -dot- com>
To: "'Robert Lauriston'" <robert -at- lauriston -dot- com>, "'TECHWR-L Writing'" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 29 Jul 2016 13:11:46 -0400


> I believe structured text is necessarily complex.

Structured text is not necessarily complex, but you would be forgiven for
thinking that it is, since most of the simple examples are not commonly
thought of as structured. For example, there is Java Doc. Java Doc is a
structured language for describing Java APIs. It is very simple. But we
don't tend to classify it as structured text, perhaps because it is not
expressed in XML.

Of course, you can't write everything in JavaDoc. It is a highly topical
language designed to serve only one purpose. That is what makes it simple.
But to write about other things you would need similarly simple languages
designed for those purposes. These are what I call subject domain languages,
and they are inherently simple because the only deal with one subject.

Up to now, that has been quite difficult to do. The toolset for doing it has
been XML, which means that writing is immediately cumbersome, and because
XML is a purely abstract language, you have to invent the entire structure

So rather than create subject domain languages, people have instead turned
to document domain languages like DocBook and now DITA. Because everyone
wants to use them to create all kinds of documents, and to do all kinds of
content management and reuse, these have become very cumbersome, very large,
and very complex. General document domain languages are indeed necessarily

DITA does, of course, attempt to provide support for subject-domain
languages through specialization. But while this can work, the underlying
infrastructure is still highly complex. It is hard to create simplicity as a
specialization of complexity.

> I see no real-world problems that would lead to adoption of Lightweight

I not claiming that there are. As I said, I admire the effort because it is
an attempt to achieve a balance of simplicity and structure. Insofar as it
remains at heart a document domain approach, however, I don't think it is
the best path to simplicity. (Which is not to say it might not be the right
choice for some problem sets.)

So my own work is focused on trying to find ways to simplify the creation of
simple subject domain languages with simple syntax, and on providing a
publishing framework for them which minimizes the management overhead.
Whether that is a needle that can actually be threaded, in a way that
content people find workable, is, of course, still TBD. But if people are
interested, I would love some feedback, some collaborators, and some beta


Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @

Re: Book on Modern Technical Writing: From: Chris Despopoulos
RE: Book on Modern Technical Writing: From: mbaker
Re: Book on Modern Technical Writing: From: Robert Lauriston

Previous by Author: RE: Book on Modern Technical Writing
Next by Author: RE: Book on Modern Technical Writing
Previous by Thread: Re: Book on Modern Technical Writing
Next by Thread: Re: Book on Modern Technical Writing

What this post helpful? Share it with friends and colleagues:

Sponsored Ads