From d3cd45212b836369c4eb24746a53c83ca913caf8 Mon Sep 17 00:00:00 2001 From: Neil Jerram Date: Tue, 8 Dec 2015 10:39:48 +0000 Subject: [PATCH] Document relationship between ways of documenting new stuff Change-Id: I55329c8add108a5a7d0d65f024b19fb2412238d6 --- doc/source/policies/blueprints.rst | 38 ++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/doc/source/policies/blueprints.rst b/doc/source/policies/blueprints.rst index feee54407..e78ba842e 100644 --- a/doc/source/policies/blueprints.rst +++ b/doc/source/policies/blueprints.rst @@ -258,3 +258,41 @@ into the next release is as follows: The specs which are moved in this way can be fast-tracked into the next release. Please note that it is required to re-propose the spec for the new release. + + +Documentation +------------- + +The above process involves two places where any given feature can start to be +documented - namely in the RFE bug, and in the spec - and in addition to those +Neutron has a substantial `developer reference guide +`_ (aka +'devref'), and user-facing docs such as the `networking guide +`_. So it might be asked: + +* What is the relationship between all of those? + +* What is the point of devref documentation, if everything has already been + described in the spec? + +The answers have been beautifully expressed in an `openstack-dev post +`_: + +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 a feature X has been implemented, we shouldn't have to go to back to its +RFE bug or spec to find information on it. The devref may reuse a lot of +content from the spec, but the spec is not maintained and the implementation +may differ in some ways from what was intended when the spec was agreed. The +devref should be kept current with refactorings, etc., of the implementation. + +Devref content should be added as part of the implementation of a new feature. +Since the spec is not maintained after the feature is implemented, the devref +should include a maintained version of the information from the spec. + +If a feature requires OS docs (4), the commit message for the feature patch +shall include 'DocImpact'. If the feature is purely a developer facing thing, +(4) is not needed. -- 2.45.2