Open Stack

----- Original Message ----- 

> From: "Lorin Hochstein" <lorin at nimbisservices.com>
> To: "Anne Gentle" <anne at openstack.org>
> Cc: "Glen Campbell" <glen.campbell at rackspace.com>,
> openstack-docs at lists.openstack.org
> Sent: Monday, April 29, 2013 9:31:15 PM
> Subject: Re: [Openstack-docs] What's Up Doc? April 25 2013

> Hi Anne:

> > 5. Doc tools updates:
> 

> > I love hearing that RedHat is testing their tools with our source. A year
> > or
> > so ago I learned about Publican at the Open Help Conference and wondered if
> > we should just re-tool. Would love to hear discussions around that -- we
> > need the maven plugin for the api.openstack.org/api-ref.html site, but
> > there
> > are certainly cases where it would be cool to completely share content and
> > tooling.
> 

> Could you say a little more about the benefits of using Publican over our
> existing tooling? In particular, I can imagine how sharing tooling with
> others would be a benefit (especially if, say, RedHat was using it for their
> own OpenStack-related docs), but how would it help us share content with
> others?

While we do use Publican for our OpenStack documentation [1] I haven't been advocating for a switch in tooling used to build openstack-manuals, nor would I consider myself in any position to do so. At the moment I have been independently working on ensuring that it's possible to perform the transformations to build content from openstack-manuals with Publican in an easily repeatable fashion. This has been relatively successful and I am currently tidying up the scripting so that I can put it up on Github and do a full write-up of what was involved.

It's been a valuable experience for me not only in terms of ensuring that we can contribute to and single source from the openstack-manuals project over the coming cycle but also in that I've been able to raise several RFEs/bugs against Publican to make such conversions easier for anyone attempting them in the future. There are definitely places where the two toolchains handle things differently (not necessarily better or worse on either side of the fence) and I think they'll become clearer in my write-up and form some useful discussion points particularly when looked over by those of you who have more experience with clouddocs-maven than I do :).

Thanks,

Steve

[1] https://access.redhat.com/site/documentation/Red_Hat_OpenStack/