<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Oct 3, 2014 at 11:26 PM, Chris Friesen <span dir="ltr"><<a href="mailto:chris.friesen@windriver.com" target="_blank">chris.friesen@windriver.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class="">On 10/03/2014 07:50 PM, Anne Gentle wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Here's my current thinking and plan of attack on multiple fronts. Oh,<br>
that analogy is so militaristic, I'd revise more peacefully but ...<br>
time. :)<br>
<br>
1. We need better page-based design and navigation for many of our docs.<br>
I'm working with the Foundation on a redesign. This may include simpler<br>
source files.<br>
2. We still need book-like output. Examples of books include the<br>
Installation Guides, Operations Guide, the Security Guide, and probably<br>
the Architecture Design Guide. Every other bit of content can go into<br>
pages if we have decent design, information architecture, navigation,<br>
and versioning. Except maybe the API reference [0], that's a special beast.<br>
3. We need better maintenance and care of app developer docs like the<br>
API Reference. This also includes simpler source files.<br>
</blockquote>
<br></span>
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?<br>
<br>
It seems silly to have to do the same work twice.  That's what computers are for. :)<br>
<br>
Or is the up-front effort too high to make it worthwhile?</blockquote><div><br></div><div>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. </div><div><br></div><div>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). :)</div><div><br></div><div>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. </div><div>Thanks -</div><div>Anne</div><div><br></div><div>[0] <a href="https://review.openstack.org/#/c/120622/">https://review.openstack.org/#/c/120622/</a><br></div><div>[1] <a href="https://review.openstack.org/#/c/117193/">https://review.openstack.org/#/c/117193/</a><br></div><div>[2] <a href="https://www.youtube.com/watch?v=n2I3PFuoNj4">https://www.youtube.com/watch?v=n2I3PFuoNj4</a><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span class=""><font color="#888888">
<br>
Chris</font></span><div class=""><div class="h5"><br>
<br>
______________________________<u></u>_________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.<u></u>org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>