Open Stack

> From: Anne Gentle <anne at openstack.org>
> > On Thu, Jul 17, 2014 at 9:24 AM, Ryan Moats <rmoats at us.ibm.com> wrote:
> > > annegentle at justwriteclick.com wrote on 07/17/2014 08:19:57 AM:
> > > > I've been starting to think that there ought to be various
> > > > infrastructure (or an "under the covers")
> > > > guides, because I've been finding places where, while the existing
> > > > documentation is essentially correct,
> > > > they are incomplete in terms of the details of what exactly is
happening.
> > > >
> > > > Adding such details would risk cluttering up the existing document
> > > > (as you've noted) and such
> > > > a set of guides could both provide deeper insight into how
> > > > particular components work and provide
> > > > a natural landing space for documentation such as this.
> > >
> > > Ryan, who's the audience for this type of under the covers doc? Are
> > > they likely to read the code anyway to get the real story? It's
> > > difficult to keep up with the under the covers story -- especially
> > > when we don't have full coverage on the covers. :)

> > I wasn't thinking of developers (I hope that they'll be reading the
code),
> > but more the folks in quality assurance/testing/field support who
likely
> > won't have the time to RTSC but need to some understanding of what is
> > happening when a particular command is issued or operation is
performed.
> >
> > Yes, I understand the coverage problem :( - that's why I'm still in
> > the "starting
> > to think" mode and wondering how useful this would be.

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

I first bumped into this idea while triaging a neutron defect and needing
to go RTSC to
understand the side effects of what was happening with a particular API
operation.

Now, I can argue that in that specific case, the neutron API documentation
should
have explained the side effects of the API operation (and yes I need to
file a bug
to that effect), but that primed the thought and when I started looking at
some of
the neutron doc defects I was seeing things that would be useful for folks
to know
without requiring RTSC but there doesn't appear to be a landing place at
this point :(

Ryan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140717/baff1bee/attachment.html>