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: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
structures.
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
architectures.
--
Ask me about the Monkey.
Sean Wheller
Technical Author
sean -at- inwords -dot- co -dot- za
+27-84-854-9408 http://www.inwords.co.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!. http://www.webworks.com/techwr-l
