Open Stack

On 4 December 2015 at 11:22, Henry Gessau <gessau at gmail.com> wrote:

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

+1

Henry, that's very concisely written :)

I'd add, if X is purely a developer facing thing, then you can stop at 3.


>
> --
> Henry
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20151204/b23eb68f/attachment.html>