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.
We do seem to stand at a crossroads today with heavy-weight tools like Frame and DITA on one side and the lightweights on the other. But I think we need a third way: something that is both lightweight and structured. I'm working on a couple of projects in that direction, but I also admire the lightweight DITA effort for trying to tread the same path.
On the subject of static site generators, though, I think they actually represent the 21st century approach. 20th century computing was heavyweight and centralized, and while there is certainly sill a role for those systems, the 21st century has been more about lightweight solutions.
Static site generators began as a revolution against the heavyweight database-driven sites like WordPress. This is partly due to the rise of client side interactivity, which means a static site can still have active pages. This made it possible to manage without server side interactivity for many cases. For instance, Tom's blog can be statically built and still have comments via Disqus -- a web service invoked from the client side. But it was also due to agile and the realization that there were huge benefits to building the simplest things that works.
We have increasingly come to see that the future lies in loose coupling. Small pieces loosely joined, in David Weinberger's words. The Web is the ultimate in loosely coupled computing, and people realized that we simply don't need a heavyweight server-side set up for many sites.
On the content side, we have been pursuing customized content for a long time, and while there have been notable successes (Amazon, for example) there has also been a growing realization that there is far less need or demand for it that we thought. I think there are several reasons for this.
* It is too difficult to get the data we need to do true customization.
* It is too hard to figure out what customizations people actually want. And, in fact, they don't know either. People tend to forage for information, their understanding of their needs growing as they search. Not every information request is like looking up a number in a phone book. You can't shortcut to the end.
* Even if you could build the interface to allow people to customize content, evidence suggest they will mostly ignore it and search. Understanding the interface is too much like hard work.
* Finally, a great deal of information needs no customization. We all want basically the same stuff. Thus Wikipedia. What content really needs is better establishment of subject and context so that a searching reader can more easily identify it as the information they need.
So this leaves a huge field for static site generators to generate content that cannot or need not be customized.
Finally, on content being distributed across multiple sites. I believe we are increasingly finding that the site is an irrelevant unit. People use pages and they find them using search, social, or links. The only thing that makes a site a site is the home page and its navigation. But home pages are being used less and less each year (the decline is quite startling an much remarked on). It matters less and less which site content is on. It matters if it is findable, usable, and navigable. Static site generators can do that. With a little of the right kind of structure, applied in the right way, they can do it very well.
Mark
-----Original Message-----
From: techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com [mailto:techwr-l-bounces+mbaker=analecta -dot- com -at- lists -dot- techwr-l -dot- com] On Behalf Of Chris Despopoulos
Sent: Thursday, July 28, 2016 6:49 AM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Book on Modern Technical Writing
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
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com
