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: Modularization of Documentation From:doc -at- edwordsmith -dot- com To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Sat, 3 Jun 2006 16:47:04 -0700
On Saturday 03 June 2006 07:57, Tony Markos wrote:
> --- siliconwriter -at- comcast -dot- net wrote:
>
> I would like to modularize (is that a word?) the
> content of the technical notes, along with the
> drawings, images, and tables that accompany them.
> Then I would like to........
I think the following test, borrowed from cognitve studies in design-problem
solving, is relevant to your task of identifying modules, but maybe only in
theory:
------------------------------
Indicators of modularity
------------------------------
An ideal module isn't connected to other modules--the designer can create it
just once, with no need to iteratively revise it when an issue arises in the
design of another module. Further, a module has no references to other
parallel modules (parallel modules = other sub-modules of a bigger module ).
Finally, modules can be designed in any arbitrary order.
-----------------------------
You would use this as a rule of thumb, along these lines: Degree of
modularity is loosely reflected in these indicators--if one or more indicator
is true, your topic is at least somewhat modular. If none are true, you can
probably infer that the topic is somewhat connected with other modules.
The good news is that modules often don't conform well to this profile of an
ideal module. So it might be useful to look at topics through this lens, to
help you fine tune them as modules, in some cases.
The bad news is that modules are created by designers as a way to decompose
complexity, but design problems are usually underspecified, leaving the
designer with a lot of flexibility in how to analyze and decompose the
problem and solution. So, while your engineers are good writers, I would
expect them to be reducing complexity when they analyze the problem, again
when they design a solution, and again when they write about it, and that
could leave you with layer upon layer of design to penetrate before you get
to the underlying modular designs of interest.
This reminds me of a joke:
A guy has a toothache so he goes to the dentist. The dentist takes a look in
his mouth and says, "I have good news and bad news. Which do you want
first?"
The guy says, "Gimme both, doc." So the dentist tells him:
"The good news is that your teeth are just fine."
"Oh boy, is that ever a relief! And the bad news, doc?"
"I'm afraid that your gums will have to come out."
Good luck!
Ned Bedinger
doc -at- edwordsmith -dot- com
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
