RE: Structured stuff for the beginner

["Janoff, Steven" <Steven -dot- Janoff -at- hologic -dot- com>]

So a form then is a subject-domain structure.

It might be worthwhile to present user documentation as a form of sorts.

Tripane and topnav online help does not seem cutting-edge.  Most web sites, when viewed on a desktop or laptop, look designed for phone screens -- long, endless scrolling of a one-size-fits-all page.

You could have a menu system of dropdown menus to choose topics or information chunks.  That may seem clunky.  But maybe you could design a form, or a better presentation of online help, that serves the user better than the typical tripane stuff.  I know topnav tries to accomplish that in some ways -- those are rollover menus.

It would be interesting to convert a user manual into the equivalent of a business form.

Steve


On Sunday, April 30, 2017 11:37 AM, mbaker -at- analecta -dot- com wrote:

Examples of subject domain structured writing are ubiquitous. If you have ever filled out a form, you have engaged in subject domain structured writing. You may think forms are not relevant because they are about data, not content. But consider how that same information got communicated before forms were invented. People wrote letters -- discursive documents -- to make their requests or report their information. 

And not all forms are purely data fields. Many forms have essay sections as well. If you have ever filled out a college application or proposed as paper to a conference, you have done subject domain structured writing. 

A lot of what technical and business writing does is to narrate data. We have had tools that turn data into narration for a long time. If you have received a benefits booklet from an insurer or read a corporate annual report, you have read a document that is composed partly of narrative generated from data. Companies like narrative science have been making strides in doing more complex and creative narration of data. Subject domain structured writing captures more of your content as data so that it is accessible to these algorithms. 

Virtually all API documentation has been done using subject domain structured writing for many years. This includes both fielded data and constrained narrative passages. There are also custom web CMS systems that use the same principles and a number of proprietary inhouse systems as well.
Cinemania, as I have mentioned earlier, was done this way, and several other large data sets besides. 

Subject domain structured writing works, and it has a history as long as document domain structured writing to show it works. That is not the issue.
The issue is, can it be extended into more of the areas of corporate and technical content that are currently being handled by document domain structured or media-domain structured systems. Technically it can, because it has been used successfully for that type of content. The real questions are more to do with implementation and culture change. 

There are significant problem in this area because subject domain structured writing is inherently much more customized than document domain. There have been attempts to do industry wide subject domain content models but they have not had much success. They tend to become less subject-specific as they become more general, often turning back into essentially document domain models by the time everyone has their say. Realistically, you need to create subject domain models yourself, and while that is not particularly difficult, most companies don't have people with the mindset to do it, and vendors don't make a lot of tools that are truly helpful. Education and tooling are therefore key to making any progress on this. 

A large part of the mindset issue has to do with the resistance of many writers to anything that is "cookie cutter". Here's the thing about cookie cutters, though. If you want consistent cookies, you should use a cookie cutter, no matter how experienced you are at making cookies. Your shapes will be more consistent and you will work quicker if you use one than if you don't. What distinguishes an experience cook from an inexperience one is not that the don't use cookie cutters, but that the design cookie cutters for their own use and that of their less experienced colleagues. 

The question, of course, is, do you actually want all your cookies to be the same shape? Do you actually want all of your installation topics, or your programming topics, or your maintenance topics, to say the same things in the same way each time? In many case, you do. In many cases, there are very specific details that readers will always need to know, or that some readers will need to know sometimes, and you will serve you readers much better if you make sure that that information is included every single time. 

I have gone through this exercise to know that even when a current set of topics seems quite diverse, when you look you find something that was said in one topic that, on reflection should be said in every topic, and something that was said in different ways in different topics that, on reflection, should be said the same way in every topic. Patterns emerge quickly once you start to look for them, and once the patterns start to emerge, people often start to realize that there are other things that should be in the patterns that are not in any of the current samples, and that there are things in some of the samples that don't belong in the pattern at all and should be elsewhere or nowhere. 

This, of course, is why people stopped doing business communication with letters and started doing it with forms. People writing letters did not always know what the other person needed to know. They forgot to include critical information, or the expressed it in inconsistent ways. Often they included irrelevant information that simply slowed down the communication.
Using forms helps business correspondents ensure that they collect all the information they need in a consistent format that is easy to find, and that they communicate consistently and provide all needed information in a consistent way. 

These are all the things that we say we want to accomplish in technical communication. Yet we resist using the very tools and techniques that would help us to accomplish them. 

Of course, not every piece of communication can be reduced to a form. You can't create a form for a novel or a philosophical essay, or even a forum post. You always have to have the capacity to include freeform writing in your content set as well. But the fact that there are cases that don't fit the model is not an argument that the model does not work. It works for all kinds of things, and it improves communication wherever there are consistent patterns in the information needs to be met. 

As to the difference between structured writing and structured authoring.
The terms are often used interchangeably, but sometimes structured writing is used to imply design and structured authoring to imply tools. But the real confusion here is that document domain structured writing/authoring systems like DITA, DocBook, and Information Mapping all use the terms structured writing and structured authoring to apply to themselves.  This is perfectly fair -- they are all structured writing systems. But structured writing/authoring is a far broader concept than that. 

This is why I use the idea of structured writing domains to distinguish between different approaches. DocBook and Information Mapping are document domain structured writing systems. DITA is at heart a document domain/management domain system with some ability to specialize into the subject domain. FrameMaker and Word are media domain structured writing systems. Structured Frame is a document domain structured writing systems. 

What I am talking about is not structured writing vs. structured authoring therefore, but subject domain structured writing/authoring vs. media domain and document domain structured writing/authoring. 

There are a number of problems that are solved by subject domain structured writing that are not solved by document domain structured writing. This includes, but is by no means limited to, the ability to design cookie cutters that make sure that you are following a consistent, reliable, proven rhetorical strategy for every piece of content you write. And yes, experienced writers will be much more consistent, and quicker, in creating that quality of content, just as business people and their customers are much more consistent and complete in communicating using forms than writing freeform letters. 

But that misses the most important point. It takes experienced writers to design those cookie cutters. And being able to capture their experience, insight, and customer research in a cookie cutter give those experience writers a means to be more productive and produce higher quality content.
Equally important, it give them a means to test their designs and to consistently apply what they learn in testing to the future content they create. 

If one of the principle reasons for adopting document domain structured writing it to be able to reuse content, one of the principle reasons for adopting subject domain structured writing is to reuse information designs. 

There are a lot of other benefits as well. Enough to write a book about, in fact. 

Mark

-----Original Message-----
From: On Behalf Of Lauren
Sent: Friday, April 28, 2017 4:06 PM
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Structured stuff for the beginner

I want to see an example of this, as well. Mark's statement asserts a claim of proof, so there is either an example that supports the claim or there is no support for the claim and the claim is false.

How has structured writing "guided" a writer in a real world application of structured writing?

How has a reader's experience been "improved" in a real world application of structured writing?

Mark is describing "structured writing" as a cookie-cutter approach to producing documentation that seems like it would be helpful for new writers learning to write provided they are producing documentation that will have all needed information according to an established rhetorical pattern. If the "established rhetorical pattern" is incomplete, then the writer will still need to be able write without the crutch of structured writing.

In following this discussion, I see what looks like more than one discussion in that there seems to be a discussion of structured writing as a methodology for how to write and structured authoring as a technology for producing reusable documentation in multiple formats.

What problem does structured writing solve that is not solved by writing experience and structured authoring?

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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