<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jul 17, 2014 at 9:24 AM, Ryan Moats <span dir="ltr"><<a href="mailto:rmoats@us.ibm.com" target="_blank">rmoats@us.ibm.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div>
<p><tt><font><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a> wrote on 07/17/2014 08:19:57 AM:</font></tt></p><div class=""><tt><font><br>
<br>
> 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. <br>
</font></tt></div><div class=""><br>
<tt><font>> <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. :)</font></tt><br>
<br>
</div><tt><font>I wasn't thinking of developers (I hope that they'll be reading the code),</font></tt><br>
<tt><font>but more the folks in quality assurance/testing/field support who likely</font></tt><br>
<tt><font>won't have the time to RTSC but need to some understanding of what is</font></tt><br>
<tt><font>happening when a particular command is issued or operation is performed.</font></tt><br>
<br>
<tt><font>Yes, I understand the coverage problem :( - that's why I'm still in the "starting</font></tt><br>
<tt><font>to think" mode and wondering how useful this would be.</font></tt><span class="HOEnZb"><font color="#888888"><br>
<br></font></span></div></blockquote><div><br></div><div>Thanks, this is useful. I'm trying to think of how people learn this type of info already. Lots of times I've seen it happen at user group meetups and at the summit -- more question and answer back-n-forth than reading. Sometimes, for SDK/API work, it's by trial and error. </div>

<div><br></div><div>Getting Devstack and Trystack available helped us make huge strides there too, DevStack can be super easy to "read" without reading code. TryStack we could do more to document. I'm also thinking about this related to the DefCore project, where it's really tough to see what the tests are testing since there are a few layers of abstraction happening.</div>

<div><br></div><div>Thanks for thinking -</div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><span class="HOEnZb"><font color="#888888">
<tt><font>Ryan</font></tt></font></span><p></p></div></blockquote></div><br></div></div>