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