This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: Modular Documentation
- From: "Matt G." <matt_g_ at hotmail dot com>
- To: docbook at lists dot oasis-open dot org
- Date: Tue, 12 Feb 2002 06:51:50 +0000
- Subject: DOCBOOK: Re: Modular Documentation
- Bcc:
What I like most about text-based markup languages is that they tend to let
you structure and manage your documentation like a software project. Such
things as automated generation and processing of parts of your document -
virtually unheard of, in the world of word processors (which is to words as
a food processor is to food) - are virtually trivial.
Anyhow, there's a point Norm made, upon which I wanted to elaborate:
>As far as the technical challenges go, one of the things you need
>to decide early on is what granularity if reuse you're interested
>in. Trying to reuse chapters or sections in different manuals is
>a much different problem than trying to reuse paragraphs.
I don't see documentation reuse as a fundamentally linear continuum. In my
documents, the block elements I reuse are mostly chapters, and a couple
sections. However, I reuse *lots* of names, terms, and phrases. This has
several advantages: virtual elimination of search-and-replace (through
centralized control within, and potentially across multiple documents),
consistent semantic markup of terms, less typing, and consistent naming
throughout a document and across multiple documents.
So, if I have a set of terms relating to a standard, perhaps an ITU spec or
an RFC, I create entities for all of these, and place them in their own
file. Every document that uses these terms includes this file (in the
document's internal subset, it declares an external parameter entity that
maps to the file with the definitions, and then it expands that entity, so
the definitions are instantiated in the document). I do the same thing for
the company verbiage, product family, document type (functional
specifications tend to use different sorts of terms than requirement
documents or design specs, for example), the product, the platform, etc.
Here's an example of the above. The main document looks like this:
<?xml version='1.0' encoding="iso-8859-1"?>
<!DOCTYPE book SYSTEM
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!-- external DTD modules definitions -->
<!ENTITY % ProductTerms SYSTEM "product_terms_xdbk.dtd">
<!-- external DTD modules expanded -->
%ProductTerms;
]>
<book>
<title>&ProdName; Design Document</title>
<chapter>
<title>Document Purpose</title>
<para>
This document describes the workings of the &ProdName;.
</para>
</chapter>
</book>
product_terms_xdbk.dtd:
<?xml version='1.0' encoding="iso-8859-1"?>
<!ENTITY ProdName "<productname>Super Widget</productname>">
Keep in mind that entities can be external or internal. You can have
parameter and parsed/unparsed (external only) entities, too. 'ProductTerms'
is the name of an external parameter entity, that corresponds to the file
'product_terms_xdbk.dtd'. When it is instantiated (the '%ProductTerms;'),
its content is expanded in place of the reference. It defines a parsed
entity, named 'ProdName'. When you reference 'ProdName' (as '&ProdName;'),
its content is expanded, in place of the reference.
It basically works like a macro preprocessor, but there are substantial
limitations in the ways that different types of entities can be used.
I'm fighting similar battles of my own. Most people just don't seem to get
it. They've accepted a certain level of manual labor in producing and
maintaining documents, and seem to have internalized the limitations of the
toy with which they try to produce documentation.
I think you have a better chance of success, if the intended users are
primarily programmer types, or if you can make your case in terms of cost
savings (both opportunity cost, and lost efficiency). Focus on the
potential DocBook offers for manageability, consistency, reproducibility,
auditability, and reuse. From these, improved quality, efficiency, and
scalability may be derived.
I taking the approach of specifying "requirements" for our engineering
documentation system. If I can get people to sign up to enough of these,
they'll buy into DocBook without even realizing it, since no other format or
toolchain could come remotely close to satisfying them.
Good luck!!
BTW, if you (i.e. your company) haven't already, consider investing in a
good SCM system. This is an important part of the formula for using DocBook
to create a truly industrial-strength documentation system. Consider using
the same SCM system as you use to manage your code. This is useful, since
some document components are very closely coupled to particular modules of
code, so you'd want to locate them, correspondingly.
Matt Gruenke
_________________________________________________________________
Send and receive Hotmail on your mobile device: http://mobile.msn.com