Re: Book on Modern Technical Writing

Subject: Re: Book on Modern Technical Writing
From: Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>
To: "techwr-l -at- lists -dot- techwr-l -dot- com" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Thu, 28 Jul 2016 10:48:45 +0000 (UTC)

Actually, I'm all for the points Tom Johnson makes about this book. I respect Tom a LOT, and he's thought quite a bit about these issues. In terms of 90% research and 10% writing, that's spot on. And keeping doc source with source code??? Perfect! The only problem I have is that developers have trouble understanding the boundary between their product and my source. Maybe that's a good thing (fosters collaboration), but I've had a few problems as a result. OTOH, I've blurred my boundary between doc and code... Fun for me as I get to implement doc-related solutions in the product. (Maybe the developers have problems with that?)

What gives me trouble is wrapped up in two words... Static Site.Â

STATIC: I agree that you should have as little processing on the server as possible -- none if you can get away with it. But we can't be locking ourselves into static content. We need to move beyond that and deliver content that assembles at the last minute. Content that uses live data from the app, live data from other sources, and maybe static data from various sources -- and the final rendering is what wraps it all into a "document" or "publication" or whatever we call it nowadays. You can (and I would say you should) do all this in the client. The client is the closest to the user, and so the client is best able to know the user's state at the moment of request.Â

SITE: Welcome to the 21st Century. With microservices, virtual machines, software-defined infrastructures, cloud providers, etc. the concept of a single machine for a single application is on the way out. By that token, a single site for all the content that pertains to such an application ultimately cannot scale. Add in the IoT, and you have a distributed environment where no two users necessarily see the same constellation of features/things in a distributed environment. That means the content has to be distributed across multiple sites.

This book talks about getting away from monolithic, server-driven sites. That's good. But I think static sites are an oversimplification. They work with simplified markup, and that is good for collaboration. But I think there's a limited life span for that approach.
Finally, about XML or other semantically rich markup... Lightweight DITA is on the horizon, and should address this issue -- and should result in collaboration tools that support it. LwDITA says that DITA != XML... XML is one of many formats to express DITA. Others include a specialized markdown, and HTML5. I would expect a JSON flavor to follow shortly. So sure, for today use Markdown flavors that work with your static site generator du Jour. But in the long run we need more semantics than that, and we need to standardize. That's where I see LwDITA fitting in.
My 0.02 â
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 @


Previous by Author: Re: Search options for local documentation sets
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