Re: Structured stuff for the beginner

["Elisa R. Sawyer" <elisawyer -at- gmail -dot- com>]

Mark, I worked with a software developer who had set up an XML database to
handle documentation that his system generated from test procedures.

I think that there are aspects of the proprietary system that he created
that have some similarity to what you are describing.

Part of the need for examples comes from the need to check that our
understanding is correct, and also to refine our understanding.

With respect to my own ideas, I think that my most successful presentation
to date included some very simple examples of how a person might write a
tutorial about using the command line. I could see people in the audience
nodding with enthusiasm and some said later that the example really helped.
they also encouraged me to find more examples.

As is true with tutorials and examples used in developer guides, sometimes
the best examples are a bit simpler than what you need in real-world
scenarios.

I do look forward to your book!

-Elisa

On Mon, May 1, 2017 at 11:06 AM, <mbaker -at- analecta -dot- com> wrote:

> 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 elisawyer -at- gmail -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
>



-- 
Elisa Rood Sawyer
~~~~~^~~~~~
Technical and Creative Writer
"Apparently there is nothing that cannot happen today." Mark Twain
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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