Hi all, Noticed that docs.cloudstack.org is down at the moment, which reminded me that we haven't come to a conclusion on this topic.
The options before us are: - A Publican-generated site from the CloudStack documentation. - A docs.cloudstack.org site powered by MindTouch wiki. The previous discussion is easily skimmable here: http://markmail.org/thread/j57gbt5g4vtbk2iw My opinion is that we should go with the Publican-generated site. It's much less maintenance and can easily be hosted on Apache infrastructure. But, please do look over the earlier thread and if you have an interest in participating in CloudStack docs - please do speak up with a preference. Thanks, Joe On Thu, Aug 16, 2012, at 02:46 PM, David Nalley wrote: > 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 -- Joe Brockmeier j...@zonker.net Twitter: @jzb http://www.dissociatedpress.net/
