some direction needed

[MAatHome]

Dear list, (apologies for the long intro)

As a programmer, I have been involved in technical writing for too long. I've used IBM script, ISIL, BookMaster, etc in the early days, through the standard set of WYSIWYGs from Adobe, etc. I really liked ISIL -> BookMaster, was able to generate documents with a layout flexibility just not seen in any of the WYSIWYGs ... imo.

So, I've found myself on the board of a carriage driving (yes, with horses) organization where we have a set of rules. Right now, its about 230 pages in Word, which is about 185 pages too many for Word (again, imo). Though our carriages seem to be a part of a different era (actually they are quite sophisticated) we perceive a need to be more efficient and flexible in how are rules are delivered. Currently, we generate a PDF from the Word document that isn't the best and we would like to generate more native formats for Kindles, iPads, iPhones, etc as well as being readable and printable. We have a number of issues to be considered, we have annual updates, we feed part of our rulebook to at least one other organization and we also have a requirement to produce customized ('per-level') rulebooks, I'd like to be able to provide customized tagging (we call various subsections "articles" for example, so I'd like to use a tag named <article>), and automatically generated TOCs and tagged indexes, and so on.

I've decided to give XML a try. It would more easily allow setting up some source control with SVN and seems like it might have the flexibility to do the conditional text inclusion as well as support all the various devices.

To do this, I've set off to become somewhat knowledgable in XML & docbook (which seemed like the right place) and have consumed (most of) some related books. I suspect many people get to this point and just turn around ... but I thought I would ask.

I have oXygen 12.2 Professional (as well as SynroSVN in my day job) and that has helped a lot, at least with html and pdf production. But I am still missing something.

So, is docbook the answer, or DITA or what? I'll need to set this all up so that anyone with a basic understanding of XML <tag></tag> will be able to edit these really simple rules. Production would also need to be simple, once set up.

My apologies if this is the wrong place or the wrong kind of question for this forum. If so, I would appreciate a pointer.

thanks,
Mike.

[Radu]

Hi Mike,

So you want editing of the XML files to be done by anyone without or with small XML expertize.
Do you consider the Oxygen Author page too complicated to be used by your potential writers?
The toolbar buttons, menus from the Author page can all be customized to remove extra items and to add your own actions. Of course this customization depends on the type of XML you are editing (Docbook, DITA, TEI, etc...).

Our Oxygen User Manual is written in DITA (we have about 1100-1200 topics) and is shared among us using the Syncro SVN Client. We also have some options set at project level so that all of us use the same preferences when editing in the Author page.
It was originally written in Docbook in a monolithic 3-4 megabytes XML document (although Docbook also allows splitting XML documents using XInclude). Both Docbook and DITA are stable XML vocabularies and you can find help for different problems in the communities.

DITA has the advantage that it allows for specialization:
http://docs.oasis-open.org/dita/v1.0/ar ... ation.html
So if you want only a small set of XML tags for your writers to use (XML tags which can have the names that you want) you can specialize the original DITA DTD's and thus invent your own restricted XML vocabulary. But if properly build, the XML vocabulary would still be DITA and you would still be able to publish it using the DITA Open Toolkit to PDF, XHTML, CHM, etc... with little of few modifications made in the publishing stage.
Specialization is not easy to accomplish and needs detailed knowledge of the DITA architecture but once you have the specialization set up every writer can use it.

So if you also want to have a look at DITA you can join the active DITA Users List:
http://tech.groups.yahoo.com/group/dita-users/

which is a very good place to ask DITA-related questions.

Regards,
Radu

[MAatHome]

Radu,

Thanks for your reply. I do want the XML to be simple enough. I think the core authors will be able to use oXygen Author, but since we are a volunteer organization there will be a few that use raw XML for their sections.

Your reply is really great. I started down the Docbook path, but really do want to be able to customize the tags as well as produce a number of different documents. It seems everytime I look under a rock there is another learning curve ... which is all fine, but I do have a finite period of time to figure it all out.

DITA does seem to offer those characteristics .... so I will go down that path, join the list, I'm all in!

I welcome any suggestions anyone might have to direct me. I'll even (especially) take examples!

thanks,