Open Stack

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