Open Stack

> -----Original Message-----
> From: Chris Friesen [mailto:chris.friesen at windriver.com]
> Sent: Saturday, October 04, 2014 1:27 PM
> To: openstack-dev at lists.openstack.org
> Subject: Re: [openstack-dev] [all][docs][tc] How to scale Documentation
> 
> On 10/03/2014 07:50 PM, Anne Gentle wrote:
> 
> > Here's my current thinking and plan of attack on multiple fronts. Oh,
> > that analogy is so militaristic, I'd revise more peacefully but ...
> > time. :)
> >
> > 1. We need better page-based design and navigation for many of our docs.
> > I'm working with the Foundation on a redesign. This may include simpler
> > source files.
> > 2. We still need book-like output. Examples of books include the
> > Installation Guides, Operations Guide, the Security Guide, and probably
> > the Architecture Design Guide. Every other bit of content can go into
> > pages if we have decent design, information architecture, navigation,
> > and versioning. Except maybe the API reference [0], that's a special beast.
> > 3. We need better maintenance and care of app developer docs like the
> > API Reference. This also includes simpler source files.
> 
> Just curious, has anyone considered rejigging things so that each
> component has a single definition of its API that could then be used to
> mechanically generate both the API validation code as well as the API
> reference documentation?

One idea related to the above, Nova will be able to provide API docs by
auto-generating the docs from JSON-Home and JSON-Schema(API validation
code). JSON-Home can provide API URLs, but it doesn't cover how to provide
JSON-Schema now. If we make a consistent way for doing that in OpenStack
components, we can get the docs on the same way/format. That was we told
on the other thread[1].

Thanks
Ken'ichi Ohmichi

---
[1]: http://lists.openstack.org/pipermail/openstack-dev/2014-October/047635.html