Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On Tue, Dec 08, 2015 at 09:03:10AM EST, Mike Spreitzer wrote: > 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? Mike brings up a good point. The one issue we need to content with is Google rankings. Specs are published at specs.openstack.org - and are going to be found by people looking to know more about an API. Especially when api-site and networking API doc needs improvement. Specs are a good starting point, but my hope would be that perhaps we go back through the specs and add a note at the top pointing to the maintained API documentation - once the feature has landed. -- Sean M. Collins __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
> From: Henry Gessau > To: "OpenStack Development Mailing List (not for usage questions)" > > Date: 12/04/2015 02:23 PM > Subject: Re: [openstack-dev] [neutron] Multiple locations for > documentation of features > > Sean M. Collins 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On 08/12/15 10:04, Mathieu Rohon wrote: Hi all, thanks for the explanation. Can you also explain how does neutron team use blueprints? how it overlaps with RFE bugs? Hi Mathieu, This is all documented, in principle, at http://docs.openstack.org/developer/neutron/policies/blueprints.html. Neil __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On 07/12/15 17:42, Sean M. Collins wrote: > On Mon, Dec 07, 2015 at 12:18:29PM EST, Carl Baldwin wrote: >> On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau wrote: >>> 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, I was also impressed by how clearly you communicated this. >> This ought to be included somewhere prominently in our >> doc/source/policies/ or somewhere like that. >> > +1 for Henry's great answer, and +1 for Carl's suggestion! > I've suggested a change for this at https://review.openstack.org/#/c/254669/. Please take a look. Neil __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
Hi all, thanks for the explanation. Can you also explain how does neutron team use blueprints? how it overlaps with RFE bugs? On Mon, Dec 7, 2015 at 6:40 PM, Sean M. Collins wrote: > On Mon, Dec 07, 2015 at 12:18:29PM EST, Carl Baldwin wrote: > > On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau wrote: > > > 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, I was also impressed by how clearly you communicated this. > > This ought to be included somewhere prominently in our > > doc/source/policies/ or somewhere like that. > > > > +1 for Henry's great answer, and +1 for Carl's suggestion! > > -- > Sean M. Collins > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On Mon, Dec 07, 2015 at 12:18:29PM EST, Carl Baldwin wrote: > On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau wrote: > > 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, I was also impressed by how clearly you communicated this. > This ought to be included somewhere prominently in our > doc/source/policies/ or somewhere like that. > +1 for Henry's great answer, and +1 for Carl's suggestion! -- Sean M. Collins __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On Fri, Dec 4, 2015 at 12:22 PM, Henry Gessau wrote: > 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, I was also impressed by how clearly you communicated this. This ought to be included somewhere prominently in our doc/source/policies/ or somewhere like that. Carl __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On 04/12/15 19:24, Henry Gessau wrote: > Sean M. Collins 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. > FWIW, that's exactly how I'd see things too. It may be well that some of a spec's text is roughly suitable for later moving to a devref or OS doc, but even so it should be re-reviewed and edited for the new context, and for any details that changed during implementation. Regards, Neil __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
2015-12-05 8:40 GMT+09:00 Armando M. : > > > On 4 December 2015 at 11:22, Henry Gessau wrote: >> >> Sean M. Collins 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. +1 too. Really well described. I think DocImpact should be used for 4. OS docs (even though DocImpact is filed to 'neutron' launchpad now) 3 devref can be added as part of a new feature patch. > >> >> >> -- >> Henry >> >> __ >> OpenStack Development Mailing List (not for usage questions) >> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > > > __ > OpenStack Development Mailing List (not for usage questions) > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
On 4 December 2015 at 11:22, Henry Gessau wrote: > Sean M. Collins 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-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [neutron] Multiple locations for documentation of features
Sean M. Collins 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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [neutron] Multiple locations for documentation of features
Hi, 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? -- Sean M. Collins __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
