RE: Structured stuff for the beginner

Subject: RE: Structured stuff for the beginner
From: <mbaker -at- analecta -dot- com>
To: "'Robert Lauriston'" <robert -at- lauriston -dot- com>, "'TECHWR-L Writing'" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 1 May 2017 14:06:53 -0400

I can't speak to the Novell system in particular, but when I was Docs
Manager at OmniMark we used a similar system based on what the company
called "microdocument architecture". It used a database forms generator for
the interface, and a SQL database for storage, but used SGML markup in the
more discursive text sections, so it could be as sophisticated as it needed
to be regarding content structures, and extend subject-domain structures
into the discursive text. Given that Simon's story comes from an SGML
conference, though, there is a high degree of likelihood that it worked the
same way.

But it is important to remember that these interfaces don't have to be all
that sophisticated to do their jobs, since they are not creating a document
preview, and most of the relationships (such as links) that would have to be
managed in the interface in a document domain system are generated from data
in a subject domain system. Media-domain and document-domain systems both
require heavyweight sophisticated editors. The subject domain does not. The
sophistication lies elsewhere. That is one of their virtues.

The downside of systems based on RDBMS forms is that they have fairly high
setup costs, which is a problem for systems that have to be customized to
the subject matter and audience to be most effective. The biggest challenge
in this area is the development of tools that ease the cost and complexity
of this customization. Pure markup systems, rather than hybrid RDBMS/markup
systems strike me as more promising in this area.

The writers we hired to work using the OmniMark system often found it a very
foreign environment at first, but uniformly came to prefer it after they had
worked with it for a while. I remember one lamenting that they could never
leave the company because they couldn't bear the thought of going back to
FrameMaker again.

This stuff is hard to grok until you get a chance to work with it. I get why
people (Robert in particular) want to see more examples. But because these
systems tend to be customized this is hard to do, because there are not a
lot of public models like DITA and DocBook to go look at (except, of course,
for the API doc tools). I can't very well develop an entire subject domain
docs platform in a forum post, nor can grant anyone access to the internal
systems of the people who are doing this.

That said, the comparison to a CMS is apt, and there are a number of custom
CMS systems that are essentially custom subject domain relational database
systems. Their limitation is that they tend to use either plain text,
markdown, or HTML for their more discursive fields, which limits their
ability to extend the subject domain structures into those fields.

The difficulty is showing people working examples, particularly markup-based
ones, rather than database-based ones, is certainly one of the reasons that
progress is stalled in this area. It is a big mental leap to make and it is
hard to take it on faith when you have not had the concrete experience of
working on it. Creating more public examples is certainly one of the things
we need to do to move this forward, and it is something I plan to work on
once the book is put to bed.

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 Robert Lauriston
Sent: Monday, May 1, 2017 12:19 PM
To: TECHWR-L Writing <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Structured stuff for the beginner

Sounds like an early CMS with a crude user interface. The forms wouldn't
have been very "smart" as regards content.

On Mon, May 1, 2017 at 9:02 AM, Simon North <simonxml -at- gmail -dot- com> wrote:
> Hi,
>
> It's probably of only peripheral interest but I can vaguely remember
> Jon Bosak relating many years ago at an SGML conference how the Novell
> Netware documentation was written using a database. Each author wrote
> into a form and the links to related information were all added
> afterwards by a separate link manager.
>
> Simon.
>
> On Mon, May 1, 2017 at 5:47 PM, Robert Lauriston
> <robert -at- lauriston -dot- com>
> wrote:
>
>> Obviously any content that could be written using a data-input form
>> could be structured in the way you're fantasizing about. You're still
>> not providing a real-world example of applying that to technical
>> documentation generally.
>>
>> You're repeating yourself without carrying your argument any further.
>>
>> On Sun, Apr 30, 2017 at 11:36 AM, <mbaker -at- analecta -dot- com> wrote:
>> > Examples of subject domain structured writing are ubiquitous. If
>> > you have ever filled out a form ...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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


Follow-Ups:

References:
Re: Structured stuff for the beginner: From: Robert Lauriston
Re: Structured stuff for the beginner: From: Simon North
Re: Structured stuff for the beginner: From: Robert Lauriston

Previous by Author: RE: Structured stuff for the beginner
Next by Author: RE: Structured stuff for the beginner
Previous by Thread: Re: Structured stuff for the beginner
Next by Thread: Re: Structured stuff for the beginner


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

Sponsored Ads


Sponsored Ads