+1 for Publican based docs website
On Sep 5, 2012, at 5:56 PM, Joe Brockmeier <j...@zonker.net> wrote: > 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/
