Re: Modularization of Documentation

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

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Modularization of Documentation: From: Tony Markos

Previous by Author: Re: Fw: Job Titles
Next by Author: Re: Agencies (clarification)
Previous by Thread: Modularization of Documentation
Next by Thread: "taboo engineering techniques" (RE: Modularization of Documentation)


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


Sponsored Ads