Page 1 of 1

Need help deciding between DITA and DOCBOOK

Posted: Thu Aug 30, 2018 3:39 pm
by daudvyd
I'm creating content for tabletop role-playing games to be distributed as PDFs and print on demand books. Perhaps the content will later be re-used to populate a website. The PDF and hardcopy formats will involve several types of text, for example: rule summaries, rule details, examples of play, narrative stories, real-world facts, and footnotes. Some of these will be in text boxes or marked with attention symbols. There will also be many images, charts, and tables. Content will not be re-used much within the 200 pages of a single product or between products. However, there will be a lot of cross-referencing (links or page numbers) and an extensive index.

I'm using Oxygen and XML because I hate working with Microsoft Word on large projects. I'd like to establish a workflow that is somewhat future-proof for the next ten years. My research suggests that the DOCBOOK format is no longer under development--which either means it is a solid, feature-complete technology--or becoming outdated. I'm not sure which. DITA formatted with CSS seems like a popular, emerging workflow. However, I'm finding my content does not neatly fit into DITA concept types, which are designed around technical help manuals. I'm not afraid of editing CSS, but if there is a XML schema and formatting option that matches my particular type of product--that would be better. I'd welcome any advice you may have.

Thank you,\
-da'ud vyd

Re: Need help deciding between DITA and DOCBOOK

Posted: Thu Aug 30, 2018 4:01 pm
by Radu
Hi,

Docbook is a mature standard, it has a great users list and has probably many existing users but most new Oxygen users orient towards DITA. Also as an XML editing application we also allocate more time towards building tools, editing improvements and publishing formats for the DITA standard.
The DITA standard can be specialized, you can create a DITA DTD specialization to add new elements or remove some of the existing ones:

http://www.xiruss.org/tutorials/dita-specialization/

so with a bit of work you may end up with a vocabulary based on DITA but using your custom tags and which could be published and editing using the default support Oxygen has for DITA.
The Docbook standard cannot be specialized, once you add new elements to it it's not Docbook anymore.
Also this idea of splitting content in many topics/concepts may in the end prove beneficial for your book's overall architecture. Even if the book is an on demand book people will never probably attempt to read it fully, they will try to navigate to a small topic somewhere which explains exactly what they want to know.
With DITA (and Docbook) you can also publish to EPUB which is searchable, adjusts better to screen layouts so it may be a better approach to delivering a PDF.

One more thing, most users registered on the Oxygen forum have not set up their settings to receive automatic updates for each post so if you want to ask the opinion of more Oxygen users you can register on the Oxygen users list and ask there:

https://www.oxygenxml.com/mailman/listinfo/oxygen-user

Regards,
Radu

Re: Need help deciding between DITA and DOCBOOK

Posted: Thu Aug 30, 2018 4:41 pm
by daudvyd
Thank you Radu. What about the different DITA formatting options such as XSL-FO and CSS? I started with XSL-FO but editing those files seems tedious and obscure. CSS already is well-established for web-pages. Do you believe it is an emerging DITA standard as well? Is Oxygen dedicated to supporting CSS? I've used the DITA to PDF via CSS tool that ships with Oxygen and it appears to work well.

Re: Need help deciding between DITA and DOCBOOK

Posted: Mon Sep 03, 2018 7:10 am
by Radu
Hi,

I would advise you to go with the CSS-based customization approach, it's easier to do, to understand and to maintain, this is our main improvement direction as well and we also have lots of documentation in our user's manual to help you customize just about everything.

Regards,
Radu

Re: Need help deciding between DITA and DOCBOOK

Posted: Mon Sep 03, 2018 8:20 am
by daudvyd
That sounds good. Thank you.

Re: Need help deciding between DITA and DOCBOOK

Posted: Thu Jan 02, 2020 12:53 am
by RBVanDyke
daudvyd wrote: Thu Aug 30, 2018 4:41 pm What about the different DITA formatting options such as XSL-FO and CSS?
I've believe I've just collided with this issue. I've been creating DocBook content as a learning exercise. It appears that getting nicely formatted and branded PDF out of DocBook requires one to go cave-diving into the XSL-FO abyss. And as best I can tell, oXygen's documentation for DocBook to PDF is somewhat confusing if not flat out inaccurate. (But I may be wrong -- all I can say is that the online help hasn't helped much...)

Cheers,
Riley
SFO

Re: Need help deciding between DITA and DOCBOOK

Posted: Mon Jan 06, 2020 4:03 pm
by Radu
Hi Riley,

For DocBook we rely almost entirely on the base DocBook XSLTs for the PDF publishing, and their documentation is available here:

http://sagehill.net/docbookxsl/CustomizingPart.html

So our user's manual does not contain much about customizing DocBook.

Regards,
Radu

Re: Need help deciding between DITA and DOCBOOK

Posted: Mon Jan 20, 2020 7:27 pm
by RBVanDyke
Thanks as always Radu. Riley, SFO...