Docbook versus Home-Grown

[Steve Rickaby]

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