Hi folks, Wanted to toss this out there and get some reaction.
We use Publican to transform our documentation XML into consumable formats like HTML, EPUB, PDF, etc. Publican has a number of other functions, and one of those is publishing a documentation website. I've participated in this with other projects, and it seems to be relatively easy. (it's literally two commands to build and publish a document) So I started playing with this today - and you can take a look at my VERY UNPOLISHED results. I only spent a few hours on this today, so there is still plenty that needs to happen for this to look presentable, but please have a look. http://people.apache.org/~ke4qqq/docs A couple of things I'll point out. The interface is completely localized in scores of languages - and it will automagically load to match your browsers locale provided there are docs in that language. To date though we only have zh_CN, and only for a single document. You can also manually set your language. The TOC on the left is divided by 'product' [1], then by version [2], and then document. I will note that you are presented with all of the formats that the document was built for (so you'll see HTML, HTML-Single, PDF and EPUB and the latter two options are download links for the docs.) And that permits you to load your content pretty easily. [1] I'd imagine we'd generally only have a single product - Apache CloudStack, but perhaps there will be others, like Apache CloudStack Contributor Documentation which is separate from user documentation [2] Selecting a version shows you all available documents for that version in your language of choice What do folks think of presenting our 'official documentation' in this manner? Is it something worth pursuing? I was thinking having this be a docs/ subdirectory on the project site (e.g. incubator.apache.org/cloudstack/docs, is there a better place for it? Thoughts, comments, or flames are welcome. --David
