Katie,
While we are being frank, I have tried so many documentation options over the years that I have lost count. The only one I liked using was IBM’s DCF, and that was 25 years ago. Docbook comes close to DCF/Bookmaster, but it isn’t quite there. The main criticism I have of Docbook is that it is incredibly complicated on the back end and when you hit a bug it’s beyond the abilities of even those who call themselves Docbook experts to fix. I have tried various Wikis, Word and Adobe Robohelp, and it’s a competition between Word and Robohelp for last position. The real strength of Docbook is that it’s part of a tool chain, so I have it hooked into Git, and whenever I get time to work on documentation I just update the Docbook file I am working on and push the change. When I push the change, Git runs the hook and rebuilds my documents in both HTML and PDF on a machine I have running at DigitalOcean. So, from my perspective, the power of Docbook isn’t just the documents it creates, it’s the fact that it is the only tool I know of that I can use as part of a toolchain. I develop and support a very specialized tool, and over the years I have all but given up on ever finding a technical writer I can work with. To be honest, the best thing for me about Docbook is that I have decided that unless someone can use Docbook they are not qualified to document my product. This means I end up writing my own manuals, but it also means I don’t waste time and money working with people who write content that I end up deleting. Here is an example of one of my manuals http://documentation-us.gazillabyte.com/book_sync.pdf Hope that helps. Gerard Nicol / CEO <mailto:[email protected]> [email protected] GazillaByte LLC 4600 S. Syracuse Street, Level 9, Suite 905, Denver Colorado USA Cell +1-720-382-8560 / Office +1-720-583-8880 <http://tapetrack.com/> http://tapetrack.com Languages English While I am always happy to answer technical support questions, I am a regular traveler and may not always be able to respond as quickly as I would like. If you send your technical support questions to <mailto:[email protected]> [email protected], a support case will be automatically created and you may get faster service. -----Original Message----- From: Katie Welles [mailto:[email protected]] Sent: Friday, September 11, 2015 10:57 AM To: [email protected] Subject: [docbook-apps] Show off what you've done with Docbook It’s been a while since I’ve used Docbook or participated in this forum. I used Docbook a number of years ago to put together a web-based API reference system. To be frank, I found it to be a pretty painful project, but mainly because I thought it was downright foolish to jump through all those Docbook hoops just to output simple HTML. It seems to me that the power of Docbook is when your single XML source is used for multiple outputs. I support a consortium that manages 12+ open APIs, and we’ve been re-examining the tools we use to output published specs. We know we want **all** our API specs to be available as PDF and also HTML, but are not sure which tool to bank on. So far we’ve been looking at asciidoc, which I find pretty underwhelming. Have any of you PDF + HTML output with Docbook? If anyone has such a project and will be willing to show it off, send some URLs! As an aside: Have any of you used asciidoc? (BTW — I use MadCap Flare for another of my clients. The output is stunningly beautiful, but the tool is far too unwieldy and expensive for me to be able to recommend it to my API client.) --------------------------------------------------------------------- To unsubscribe, e-mail: <mailto:[email protected]> [email protected] For additional commands, e-mail: <mailto:[email protected]> [email protected]
