Open Stack

On 2022-01-18 11:14:59 -0800 (-0800), Julia Kreger wrote:
> On Tue, Jan 18, 2022 at 10:49 AM Jeremy Stanley <fungi at yuggoth.org> wrote:
> >
> > On 2022-01-18 23:21:21 +0500 (+0500), Mahnoor Asghar wrote:
> > [...]
> > > I am an Outreachy intern, working with OpenStack Ironic on improving
> > > their API reference documentation mechanism.
> > [...]
> >
> > Welcome!
> >
> > > The wider OpenStack community may be facing similar problems
> > > maintaining their documentation, and it would be helpful to
> > > understand their perspective and concerns - with respect to using
> > > such an extension, their expectations from it, collaborating on
> > > it, and whether they have additional ideas about how we may bring
> > > API documentation closer to the code.
> > [...]
> >
> > Keep in mind that developers of OpenStack's services have
> > traditionally held the belief that a good public API should be
> > versioned independently from the software which implements it. One
> > version of the software may provide multiple API versions, and
> > there's not necessarily a 1:1 correlation between public REST API
> > methods and the internal Python API methods which implement them. I
> > suspect this has driven some of the desire to separate REST API
> > documentation from the source code itself.
> 
> And the API version contracts we've tended to offer has been a very
> linear progression matching the software versions, for the most part.
> I think as the groups of maintainers have evolved, I believe the
> traditional belief may no longer really hold true. Or at least, there
> doesn't seem to be a good reason to continue to keep aspects
> disjointed and separated, at least that I'm aware of. I guess to put
> it another way, we have finite capacity/bandwidth, and anything we do
> to reduce hurdles, can help us further our work.
[...]

Absolutely, that's why I qualified it with "traditionally" (many may
no longer feel this way, or the people who made those choices may no
longer be around/involved in their respective projects). I'm in
favor of the Ironic team pursuing whatever makes documenting easier,
just noting that the approach may not be applicable OpenStack-wide
for these or other reasons.
-- 
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-discuss/attachments/20220118/2a0c64d3/attachment.sig>