Re: Modularization of Documentation

Subject: Re: Modularization of Documentation
From: Sean Wheller <sean -at- inwords -dot- co -dot- za>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Date: Mon, 5 Jun 2006 21:57:57 +0200

On Monday 05 June 2006 20:27, Tony Markos wrote:
> How does DITA prod you to ensure that your modules are
> highly cohesive and losely coupled?  That is the
> essence of an effect modularization.  My on-line
> research revealed nothing.

When is someting off-topic?

As a writer you know.

Technically the structured nature of DITA or DocBook make it very easy to
write a topic and place that content into a single file containing a single
block structure, or comprise a topic of several files containing block

Everything can be an object, a chapter, a section, a paragraph, an itemized
list, an ordered list, a procedure. It all depends on just on just how
granular you want or need to go in order to achieve a level of indirection
that will make a piece of information useful in multiple contexts.

If the content is written with modularity in mind, in other words the intent
is that the content should be reusable and capable of being repurposed, then
implimentation of this writing style in conjunction with the technical nature
of the structures provided by DITA or Docbook will naturally implement "one
possability" of the many that may exist for a given situation.

However, modularity is not solely about blocks of content. It is even possible
to create a file from a inline content, a phrase for example, and when that
element is outside of its applicable context it is a block that can be used
countless times.

Another example of this would be menu choices.

In docbook I modularize menu choices. Each menu and option sequence is placed
in a single file containing something like this:


This single instance of the File > Open is declared as an entity that is
globally available throughout the documentation set of a product. The result
is that in order to insert the menu choice "File > Open" in any position
within my content I need just call the file containing this information using
an entity reference. The entity reference looks like this, &mnu-FileOpen; and
is defined in a central file like such:
<!ENTITY mnu-FileOpen SYSTEM '../menus/mnu-FileOpen.xml'>

The question is, "How far down the Rabbit hole are you prepared to go?"

The possabilities are endless. For any one given situation there may be
countless permutations. All of which are justified in being called modular

Ask me about the Monkey.

Sean Wheller
Technical Author
sean -at- inwords -dot- co -dot- za

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!.

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

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

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 for more resources and info.

Re: Modularization of Documentation: From: Tony Markos

Previous by Author: Re: Modularization of Documentation
Next by Author: Re: pace (RE: "taboo engineering techniques" (RE: Modularization of Documentation))
Previous by Thread: Re: Modularization of Documentation
Next by Thread: RE: Modularization of Documentation

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

Sponsored Ads