We are facing a decision on documentation platform for a number of our internal projects and as we use gradle for our builds I figured it might be worth asking this question. The projects would need customer facing documentation of a similar nature as the gradle user guide and DSL reference.
What are your general impressions from using docbook for the user guide, DSL reference, etc? Are there any good wysiwyg editors out there for docbook? Would you use one even if one existed (or do you guys all just use ed :)? Any pain points? Benefits?
I know this is a general question, but as I think the gradle documentation is very high quality and has a nice and clean presentation and format I would be interested in the gradle teams impressions.
We do plan to turn the user guide and DSL reference generation stuff into a real plugin that you can use to publish documentation about your custom plugins and other build infrastructure. So, this might solve your problem.
I would imagine that such a plugin would eventually end up supporting various different documentation formats. It would allow docs to be written in docbook, but might also allow you to mix in, say, docs written in markdown.
As far as docbook itself goes, there are some advantages and disadvantages. From an authoring point of view, some advantages: * The model is very rich, which can be useful at times for creating precise docs, and allowing the tooling to do interesting things. * It’s possible to aggregate a larger document from smaller pieces. * The tooling runs on the jvm, and is available in various repos, so that you can just clone the gradle repository and start working on the docs, without needing to install anything.
Some disadvantages: * It’s a pain to write documentation in XML. * The tooling is very slow.
From an automation point of view, there are some big advantages, as the documentation ends up as XML with a rich model, so it is easy to chain a bunch of transformations, to mix in some generated the content, and so on.
In other words: For the author, docbook is a pain. For the tooling, docbook is good.
What I’d like to do with our documentation system is to come up with a way to allow user guide chapters and DSL reference material to be written in either markdown (or similar) or docbook - whichever is appropriate for that content - and have the tooling merge this content into a single docbook document that travels down the tool chain.