Open Stack

On Aug 6, 2012, at 11:50 AM, Doug Hellmann <doug.hellmann at gmail.com> wrote:

> 
> On Aug 5, 2012, at 3:20 PM, Anne Gentle wrote:
> 
>> Hey all, sorry for top posting but I'm not sure how to insert comments without sounding weird. :) 
>> 
>> I'm completely fine with starting it in DocBook, (I <3 markup, hee hee) but I had two concerns really, one about the markup authors want, and another about the license for the Operations manual chapters. 
>> 
>> I've been talking to Debra at Pearson, on the To: line (Hi Debra!) and we are looking for authors for some of the operations chapters to be part of a larger book about running and deploying OpenStack. So I would love for you to start as author but want to be sure it's okay that the license is such that we're sharing those chapters with Pearson for a larger book. The outline is http://etherpad.openstack.org/EssexOperationsGuide for the operations part, and Doug Hellman and I have worked on an outline for the "Developing" part at http://etherpad.openstack.org/PythonDevBookOutline. The two together comprise a book proposal for Pearson. 
>> 
>> Debra, if you have any pointers for the "source" files that would help us decide amongst DocBook or markdown or asciidoc, let us know. 
> 
> I have a bit of experience with DocBook, and IIRC it was an option with Pearson. My book was done with Sphinx and LaTeX with only moderate pain during the compositing phase.
> 
>> 
>> I'm trying to be transparent about the re-uses that operations manual can be used for and make sure we're all good with it. I know I am - sharing content with a 3rd party publisher sounds like the best of two worlds to me. But I welcome discussion - thanks Jon for bringing it to the mailing list, sorry I didn't do so sooner. Please discuss. :) 
>> 
>> I think one good path is:
>> 1. Un-abandon review 10487. 
>> 2. In the book file make sure CC licensing is set. 
>> 3. Start writing based on the outline.
>> 4. Rock out.
>> 5. Do maintenance going forward in a common authoring environment. 
> 
> Anything that makes merging and collaborating easy works for me. What tools are the group used to working with?
> 
> Doug
> 

The docs maintained by the doc team are pretty much all in docbook format, with maven scripts used to generate the output. I believe Anne has been using pandoc to convert from other formats when people contribute in other formats, but that hasn't happened too much. The dev teams use Sphinx.

At this point, I have no problem with DocBook, as I've been working with it for a while now, and Oxygen makes it much easier to edit DocBook files since they give us free licenses (see http://wiki.openstack.org/Documentation/HowTo). I do think it takes a bit of time to ramp up with the tools.

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/20120808/dd9fe179/attachment.html>