Open Stack

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

> 
> Thoughts?
> 
> Anne
> 
> On Sun, Aug 5, 2012 at 1:49 PM, Jonathan Proulx <jon at jonproulx.com> wrote:
> I'd really like to have an operations manual to read but since it's
> not written yet and I need to start writing internal operations
> documentation I'd be happy to help write it as I go...
> 
> In https://review.openstack.org/#/c/10487
> 
> Tom translated the etherpad outline at
> http://etherpad.openstack.org/EssexOperationsGuide into docbook.  Anne
> expressed concern about setting the mark up format and scaring off
> potential contributors.  Lorin expressed some support for trying out a
> lighter markup to see if that attracted more authors and someone of
> that set of people suggested moving the discussion to this mailing
> list.
> 
> I've not see any discussion here so let's discuss :)
> 
> I don't have any background in document markup, only even looked at
> docbook maybe two weeks ago when I was trying to figure out my first
> documentation bug fix, so I don't have any particular opinions other
> than thinking we should set something so that it's possible for
> authors to start contributing.  There's a lot of value in using the
> lightest markup that will do everything we need but there's also value
> in sticking to a single markup standard especially when someone has
> contributed an outline in that.
> 
> I suppose my vote would be to accept
> https://review.openstack.org/#/c/10487 and start building from there
> but if someone wanted to contribute the equivalent in another markup I
> wouldn't be opposed.
> 
> -Jon
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20120806/04b9eccd/attachment.html>