Docbook versus Home-Grown

[Joe Malin]

Thanks for the quick reply. I have worked in structured FM before, using
someone else's EDD. I think I understand structure pretty well. I have
worked with XML and HTML quite extensively both as a software developer
and as a writer. 

I don't mind writing an EDD from the ground up. What I want to avoid is
producing an EDD that is off-track from easy conversion to DocBook XML.
My overall goal is to convert my unstructured FM to structured FM and
then to XML on the way to HTML. Obviously this will be a long project. 

One of the important constraints is that I have to do it for 0 dollars.
Though I want to have single-source and people here like the idea, I
don't think anyone here needs it urgently enough to spend money on it,
yet.

Joe

	 Joe Malin
Technical Writer
(408)625-1623
jmalin at tuvox.com 
www.tuvox.com
The views expressed in this document are those of the sender, and do not
necessarily reflect those of TuVox, Inc.	
-----Original Message-----
From: Steve Rickaby [mailto:srickaby at wordmongers.demon.co.uk] 
Sent: Sunday, October 08, 2006 4:36 AM
To: Joe Malin
Cc: framers at FrameUsers.com
Subject: Re: Docbook versus Home-Grown

At 11:22 -0700 7/10/06, Joe Malin wrote:

>Well, I *finally* finished the new book for our next software release,
so I can justifiably turn my attention to getting myself into structured
docs.
>
>I am not going to go with DITA just yet. My plan is to convert my
existing unstructured docs to structure first, and then start the next
round of docs in DITA. So, my first decision is what EDD to use. Should
I develop an EDD myself from scratch, or start with the DocBook EDD? My
only hesitation in using the DocBook EDD is that it will have a lot of
elements that I don't want to use.
>
>Any advice, particularly from those who have gone the same route, would
be much appreciated.

Hi Joe

I was in exactly the same position about a year and a half ago, and was
involved in a most helpful discussion with several structured experts on
this list, so first off you should fine some relevant stuff in the
archives. One thread was titled 'Structured Frame novice falls in at the
deep end' (that was me), another 'Structure/Schema - Custom or off the
shelf?'. If that fails for you, mail me off-list and I'll forward
something.

The issue you raise is a big one and one that can have ramifications
down the line. In the end, the right route for me was a 'roll your own'
EDD, but that doesn't mean that it's the right one for you. I think of
it as the 'BigSmall' decision, but that will have no resonances for
anyone who doesn't watch UK commercial television (it features on a
Toyota ad for the Yaris).

There are many pros and cons in both approaches. If you are new to
structure, as I was, you will be floundering in trying to cut down a big
EDD, whereas with familiarity it would not be too bad a job. Conversely,
again if you are new to structure, writing your own simple EDD from the
ground up is a great way to learn.

There is also Scriptorium's 'DocFrame' product, which as I understand it
is DocBook tamed: <http://www.scriptorium.com/docframe/index.html>. I
believe that there are people on the list who have used it, although I
haven't. Clearly, you have to pay for it.


Orthogonal to the decision you are battling with, and applying only if
you 'roll your own', is the decision over how much authority you will
give the EDD over formatting. Again, molto argumentos. Some things, such
as indented lists, are easier if the EDD is given some formatting
authority (ie. 'if level 2, set indent to X'), although my current
preference is to keep structure and presentation completely separate,
the first in the EDD  (i.e. 'if list level 2, set para tag X') and the
second in the template. This is in line with what I beleive software
folks refer to as 'the principle of the separation of concerns'.

HTH

-- 
Steve