TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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 | http://techwhirl.com
