TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Structure vs. Substance? From:"Michele Marques" <mmarques -at- cms400 -dot- com> To:techwr-l -at- lists -dot- raycomm -dot- com Date:Tue, 13 Jun 2000 10:58:42 -0400
I think part of our problem with this discussion is that we are not all
arguing about the same things.
Some of this structure/substance debate is about procedures - and
the quantity of procedures required. While other parts of this
debate are about whether a structure (and how abstract a
structure) can be applied to a document (whether before or after
content is available).
I'm not going to get into the procedure debate...
With regards to structure/substance, I believe that the best
document structures take into account the type of content they will
hold. I may start with the most abstract form of structure before
seeing content, but then I must refine it and flesh it out when I
receive content. The structure may be further refined as I use it for
other (related) content that doesn't completely fit the structure.
The consistent application of the structure helps:
(1) when documenting additional content, as I have places and
patterns to plug in the content.
(2) the user who is using the document. If the document is being
used as a reference, the user knows where to quickly locate the
information (e.g., whether or not a field is mandatory is mentioned
at the beginning of each field definition, and field names are
emphasized).
I have come into situations where people "just wrote" the
documentation without any structure in mind (or perhaps trying to
vary structure in belief that this would keep the document more
interesting). The users couldn't locate information they were
searching for, and it was difficult for writers to tell if all required
points about the content were included.
On the other hand, the structure must be relevant for the content,
or else it won't help (and may even confuse matters).
My understanding of XML was that it helped for the (structural) tags
to be related to the type of content, because then a user (or writer
hoping to re-use content) can search for instance of that type of
tag. For example, you might have tags for warning, definition,
overview, etc. instead of re-using the generic paragraph tag for each
of those three types of paragraph. Even generic heading and list
tags relate to the content in that you must have enough levels of
heading and levels of list to cover the needs of the content.
But, no Andrew, I don't spend hours developping the structure: I
have a general plan in mind, start writing the docs, find some
structure starting to come out and then make sure that this
structure is consistently applied. Sometimes when trying to apply
the structure consistently I realize that I need to go back for more
content (e.g., I see that I am missing the results of a couple of
steps).
-------------------------------------------------------
Michele Marques
Lead Technical Communicator, CMS Manufacturing Systems
mmarques -at- cms400 -dot- com
905-477-4499 x280
