Open Stack

On Fri, Oct 3, 2014 at 11:26 PM, Chris Friesen <chris.friesen at windriver.com>
wrote:

> 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?


To me, the upfront effort is better spent in better API docs. Starting with
generated is fine, but generated API reference documentation doesn't tell
users or quality engineers what's intended so that they can test APIs or
write apps that won't break. Some reviewers were going to allow 200-299
error codes to get into the docs as a valid response since that's what the
code does. [0] [1] That doesn't help users.

We do talk about generating API docs, and testing APIs, and testing SDKs,
quite a bit. Check out yesterday's Bootstrapping Hour [3] for more
discussion about the balancing act and tradeoffs in generated docs. I know
I toe the line a lot (not tow the line in this case, literally my toes are
on a fine line). :)

So great to know we're all thinking through this. It's a huge effort and we
should optimize within an inch of that line.
Thanks -
Anne

[0] https://review.openstack.org/#/c/120622/
[1] https://review.openstack.org/#/c/117193/
[2] https://www.youtube.com/watch?v=n2I3PFuoNj4


>
> Chris
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141004/16418a33/attachment.html>