Re: Book on Modern Technical Writing

[Chris Despopoulos <despopoulos_chriss -at- yahoo -dot- com>]

Mark, I think we're largely in agreement. For sure, I'm not suggesting centralized delivery in any way. I'm squarely in favor of distributed delivery. And also in favor of loose coupling... Just because your "doc set" includes x, y, and z, that doesn't mean mine should or will.
At the risk of starting a terminology war, I'll say that what I mean by site is the actual domain from which the content is served... Or possibly a subset of that domain. Foo.com is a site. By that definition, Foo.com/product_a and Foo.com/product_b are both from the same site, even though they might each have their own content sets, each produced by a "static site generator". For me, the interesting thing is opening up the web. BTW, this is the one server side thing you need to do... make cross-domain access. But it's very small and light.

About dynamic content... "Customized" content is just one of many approaches. Simple examples include filtering by user role or product state -- passively omitting categories of content. But there's more. Dynamic content can get the current state of a system and integrate that into your rendering. For example, you document a chart that shows some state in your system. Your docs can include static content ("This chart is a foo, and it shows bars"), AND it can include dynamic content ("This chart shows 6 bars in your primary foo"). Another type of dynamics would be to merge content from multiple "sites", so that you see a unique "doc set" according to your profile or state. This is more than filtering because it actively brings in remote content without knowing a priori what that content includes. And there's the example you mention, where Tom's blog integrates disqus comments. More generally, integrating content from a centralized repository within your distributed content. 

So I'm not willing to give up on dynamic content. In fact, I can demonstrate all of these in my current documentation framework... In addition, I can implement my framework as part of a product GUI, and integrate DITA content directly in the product GUI. All this requires dynamics on the client side.

The bottom line here is, the content is static or dynamic, depending on the source -- dynamic if it comes from an API, static if it comes from source XML files. The rendering is dynamic. DITA provides a mechanism (conref) to inject dynamics wherever you want, or fall through to static content if the dynamics don't resolve to anything. If the customer installs remote components, the docs live on those components and the user gets the doc automatically.
So I'm thinking that static sites are not anything new or amazing in and of themselves. Shoot, they're old-school at the bottom of it. What's new is on the client side. The ability to dynamically render at the last minute is where I think we're headed. Wherever the content comes from, adjusting it to suit the reader at the last minute is key.

      From: "mbaker -at- analecta -dot- com" <mbaker -at- analecta -dot- com>
 To: 'Chris Despopoulos' <despopoulos_chriss -at- yahoo -dot- com>; techwr-l -at- lists -dot- techwr-l -dot- com 
 Sent: Thursday, July 28, 2016 10:49 PM
 Subject: RE: Book on Modern Technical Writing
   
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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as mbaker -at- analecta -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 http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

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