Open Stack

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.

-- 
Henry