This is the mail archive of the docbook@lists.oasis-open.org mailing list for the DocBook project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Modular Documentation


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]