Open Stack

#
> 
> Plain text is great, and asciidoc is a clear winner from the OpenStack docs perspective
> due to our existing build tools being able to handle it. It converts to docbook easily.
> However, I'm not sure if this document you are talking about needs to be published in any
> other format other than plain text? If you just need a web page to point to, you might not
> need to go through the trouble of publishing and could just use github's markdown and
> point to the github page. https://help.github.com/articles/github-flavored-markdown

True. Not much needed to convert to other formats, as near as I know. But would like see a
consensus here.

Just this morning I noticed github supports asciidoc markup. Sweet!


> 
>     Cons:
> 
>       (1) Integration with Jenkins, etc ?
>             - That's only needed for automation tests.
> 
> 
> We can integrate and build API docs starting with asciidoc, markdown, or rst. API docs so
> far are in docbook, WADL, or markdown. We have the High Availability guide in asciidoc.

Agreed.


>       (4) I haven't seen any eamples of folks using text file based approach (that
>           doesn't mean it shouldn't be explored.
> 
> 
> Take a look at the github.com/openstack/ <http://github.com/openstack/><project>-api
> repositories to see how API docs are being maintained now.

Thank you, will do.

I'm a little swamped with a zillion other things, I really should manage my time better.
> 
> 
> (5) Tables are difficult to create and maintain in nearly all plain text markups (if you
> need to add a column it's a pain, for example.)

Fair points.

Thanks for this response, Anne.

-- 
/kashyap