RE: Structured stuff for the beginner

Subject: RE: Structured stuff for the beginner
From: <mbaker -at- analecta -dot- com>
To: "'Lauren'" <lauren -at- writeco -dot- net>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 30 Apr 2017 14:36:59 -0400

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


References:
Structured stuff for the beginner: From: Dave C
RE: Structured stuff for the beginner: From: mbaker
RE: Structured stuff for the beginner: From: Rick Quatro
RE: Structured stuff for the beginner: From: mbaker
Re: Structured stuff for the beginner: From: Lauren

Previous by Author: RE: Structured stuff for the beginner
Next by Author: time "period" vs. time "interval" ?
Previous by Thread: Re: Structured stuff for the beginner
Next by Thread: Grammar: "Multiply by" or "Multiply times"?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads