> -----Original Message----- > From: Chris Friesen [mailto:chris.frie...@windriver.com] > Sent: Saturday, October 04, 2014 1:27 PM > To: openstack-dev@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 _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
