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?
It seems silly to have to do the same work twice. That's what computers
are for. :)
Or is the up-front effort too high to make it worthwhile?
Chris
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
