Open Stack

> From: Henry Gessau <gessau at gmail.com>
> To: "OpenStack Development Mailing List (not for usage questions)" 
> <openstack-dev at lists.openstack.org>
> Date: 12/04/2015 02:23 PM
> Subject: Re: [openstack-dev] [neutron] Multiple locations for 
> documentation of features
> 
> Sean M. Collins <sean at coreitpro.com> wrote:
> > I've noticed that a lot of features are now being documented as RSTs
> > inside of devref. Like the following:
> > 
> > https://review.openstack.org/#/c/251859/
> > 
> > But there are lots already present. Can someone point out to me what 
the
> > criteria is for these documents? I am a little confused about the
> > relationship between neutron-specs, RFE bugs, and some features being
> > documented in devref. Especially when a review includes the actual 
code,
> > then a new RST file in devref - wasn't that what specs were for?
> 
> Here is how I would like to see things ending up:
> 
> 1. RFE: "I want X"
> 2. Spec: "I plan to implement X like this"
> 3. devref: "How X is implemented and how to extend it"
> 4. OS docs: "API and guide for using X"
> 
> Once X is implemented I don't want to have to go to 1 or 2 to find 
information
> on it. The devref may have a lot of content from the spec, but the spec 
is not
> maintained and the implementation may differ in some ways. The devref 
should
> be kept current with refactorings, etc. of the implementation.

Lots cheers from me too.  Let me add one thing: "the spec is not 
maintained" is a remaining process bug.  A spec by itself is a very useful 
thing.  It is the first thing to read when trying to understand the 
implementation.  How about we resolve that devref includes a maintained 
version of the spec?

Regards,
Mike

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151208/36e61321/attachment.html>