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.
Structure may flow from functionality but functionality flows from some
brilliant mind(s) that came up with an idea for what the software should
contain--the CONTENT.
Much of my experience is with documenting software still under development.
So I write specs, I develop UI, and create the content way before (reality
check-at the same time) as I am creating end user doc, training materials,
and marketing stuff. I have outlines in my head, drafts out for review, and
constant rewriting based on changes to the content, not the structure.
Again, the point was made that you can't separate content and structure and
come up with something useful to your intended audience. To you the
structure of the doc is the be all and end all, to me it's the users being
able to actually use product, and that takes well-designed,
well-communicated content.
Not only do we need to avoid assuming all TW's write software doc, we need
to remember that many of us are intimately involved in creating the stuff we
document. To further your analogy, I'm designing the bottle and label for
next year's vintage, stomping the grapes, and watching it ferment, at the
same time I'm putting the stuff from the previous batch on the assembly
line, and checking to see if the customers can pour out from the bottle
without drowning themselves.
Methinks you enjoy being the cog--for myself I'd much rather be the whole
wheel.
BTW, I think it's lovely that you have developers willing to test your help
files--in my world, I rely on me, the QA folks when they have time, and the
other writer on staff. Amazing how much the users love the help files,
despite not having the staff available for such a great structure.
Ok, so I'm really going to stop clucking (for at least today0
Connie Giordano
-----Original Message-----
From: Tim Altom [mailto:taltom -at- simplywritten -dot- com]
Sent: Monday, June 12, 2000 5:05 PM
To: TECHWR-L
Subject: Re: Structure vs. Substance?
We MUST separate them, because often projects depend on our ability to do
so. In our world, "content" is text, graphics, or other material that
directly communicates a concept or fact. "Structure" is the order and
organization of that material. "Layout" is the visual or aural
representation of the content. Simply put, structure is the way the missile
is designed, content is the payload, and layout is the paint job.
When I design a structure, I don't need to know the first word or concept.
The product can be software, a robot, or a procedure. It doesn't matter. The
order of presentation, the organizational pattern, and the hierarchy remain
the same for each type of communication. For example, I may know that I want
three sections, that each section will have a number of chapters (I don't
care how many at this stage) and that each chapter will have specific types
of headings, each containing certain permitted types of information (paras,
tables, graphics, etc.). I make sure that each element is given its own tag
and place in the hierarchy. This planning now permits me to set up and test
mappings, downstream filters, and other attachments. It also permits me to
start training writers in how this document will be produced. At both ends
of the production cycle, I can start buckling together my assembly line. All
without a single word being written. In point of fact, I may not even know
what the product is, although I usually do.
[snip]
All without one word of real text being applied. All I have to do is pour
the wine drop-by-drop into the bottle I've created. I can now create,
change, shift, and masticate the words and graphics without affecting my
assembly line one bit. I can, if you will, drain out the wine if it's not
correct and just pour in some new. The bottle must remain the same shape to
fit onto the assembly line with all the other project components.
The key to being able to do this is the document specification, which is the
analogue of the engineer's specification for the product. The doc spec
defines what the document is to DO, not how it's to look. Structure flows
from functionality, not from content.
