Open Stack

On Mon, Apr 29, 2013 at 8:31 PM, Lorin Hochstein
<lorin at nimbisservices.com>wrote:

> 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?
>
>
Hi Lorin,
Great questions. I have to 'splain myself some more.

Early on when I just got started with OpenStack docs, the only existing
docs were API specs. They were Docbook and built with ant. Then we hired
someone at Rackspace to create a Maven plugin. At the time we didn't really
know about Publican. I found out about Publican about a year ago, last
summer at the Open Help Conference.

Content sharing only made sense for the APIs -- Rackspace, HP, others
should just consume our API docs (and do to a point) so there's a single
source of truth. There may be more use cases for content sharing in the
operations/install space now that the distros are looking into it and I
think there's some possibilities there with careful information
architecture especially for install and configuration. If you think about
it, we currently share about 80% of install content between ubuntu and
fedora/rhel/centos with our conditionally-output install guides.

With Maven, we can do "fancier" API output like
api.openstack.org/api-ref.html. So I think we need 2 toolchains, but I hate
to duplicate effort and there are overlapping features especially around
translation. So it might make sense in the future to use Publican for
operations/configuration guides and Maven for API guides. Who knows what
the future brings so it's always good to look for efficiencies in process
and tooling.

Anne




> Take care,
>
> Lorin
>
> --
> Lorin Hochstein
> Lead Architect - Cloud Services
> Nimbis Services, Inc.
> www.nimbisservices.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130430/09d4bcfc/attachment.html>