<html><body>
<p><tt><font size="2">> From: Anne Gentle <anne@openstack.org></font></tt><br>
<tt><font size="2">> > On Thu, Jul 17, 2014 at 9:24 AM, Ryan Moats <rmoats@us.ibm.com> wrote:</font></tt><br>
<tt><font size="2">> > > annegentle@justwriteclick.com wrote on 07/17/2014 08:19:57 AM:</font></tt><br>
<tt><font size="2">> > > > I've been starting to think that there ought to be various <br>
> > > > infrastructure (or an "under the covers") <br>
> > > > guides, because I've been finding places where, while the existing <br>
> > > > documentation is essentially correct,<br>
> > > > they are incomplete in terms of the details of what exactly is happening. <br>
> > > > <br>
> > > > Adding such details would risk cluttering up the existing document <br>
> > > > (as you've noted) and such<br>
> > > > a set of guides could both provide deeper insight into how <br>
> > > > particular components work and provide <br>
> > > > a natural landing space for documentation such as this. </font></tt><br>
<tt><font size="2">> > > <br>
> > > Ryan, who's the audience for this type of under the covers doc? Are <br>
> > > they likely to read the code anyway to get the real story? It's <br>
> > > difficult to keep up with the under the covers story -- especially <br>
> > > when we don't have full coverage on the covers. :)<br>
</font></tt><br>
<tt><font size="2">> > I wasn't thinking of developers (I hope that they'll be reading the code),<br>
> > but more the folks in quality assurance/testing/field support who likely<br>
> > won't have the time to RTSC but need to some understanding of what is<br>
> > happening when a particular command is issued or operation is performed.<br>
> > <br>
> > Yes, I understand the coverage problem :( - that's why I'm still in <br>
> > the "starting<br>
> > to think" mode and wondering how useful this would be.<br>
</font></tt><br>
<tt><font size="2">> Thanks, this is useful. I'm trying to think of how people learn this<br>
> type of info already. Lots of times I've seen it happen at user <br>
> group meetups and at the summit -- more question and answer back-n-<br>
> forth than reading. Sometimes, for SDK/API work, it's by trial and error. </font></tt><br>
<tt><font size="2">> <br>
> Getting Devstack and Trystack available helped us make huge strides <br>
> there too, DevStack can be super easy to "read" without reading <br>
> code. TryStack we could do more to document. I'm also thinking about<br>
> this related to the DefCore project, where it's really tough to see <br>
> what the tests are testing since there are a few layers of <br>
> abstraction happening.</font></tt><br>
<br>
<tt><font size="2">I first bumped into this idea while triaging a neutron defect and needing to go RTSC to</font></tt><br>
<tt><font size="2">understand the side effects of what was happening with a particular API operation.</font></tt><br>
<br>
<tt><font size="2">Now, I can argue that in that specific case, the neutron API documentation should</font></tt><br>
<tt><font size="2">have explained the side effects of the API operation (and yes I need to file a bug</font></tt><br>
<tt><font size="2">to that effect), but that primed the thought and when I started looking at some of</font></tt><br>
<tt><font size="2">the neutron doc defects I was seeing things that would be useful for folks to know</font></tt><br>
<tt><font size="2">without requiring RTSC but there doesn't appear to be a landing place at this point :(</font></tt><br>
<br>
<tt><font size="2">Ryan</font></tt><br>
</body></html>