Open Stack

On Thu, 2019-03-28 at 06:47 -0700, Matt Riedemann wrote:
> On 3/28/2019 4:21 AM, Sean Mooney wrote:
> > i am personally not a fan of updating spec after they have been appoved but
> > since that is something we allow it makes sense to me to make it easier too do.
> 
> Ideally people wouldn't need to update specs after they are approved, 
> but each spec varies in how much detail it has and those details can 
> change once you get into code review, so sometimes it's good to update 
> the spec later so it's not misleading if someone is reading the spec 
> because there is otherwise a lack of docs about the feature. The best 
> way to avoid having to update specs after approval IMO is to make sure 
> when developing a feature you also have solid documentation outside of 
> the spec to go with it, and sometimes getting developers to write useful 
> feature documentation is like pulling teeth.
ya i use specs as docs far more then i proably should as they often end up
being the best developer focused docs we have.

my distaste form updating specs retroactivly only comes form the fact that we
can endup looseing the original intent of the spec. but i agree that if something
is only partially updated or we diverge for technicall reasons that only become 
apparent have  accurate content in the spec is important.

when we removed the devref section of the docs i think we lost somethign valuable
that only the spec provide now. i know we have some dev docs in the contibutor and
reference section of our docs but i think that our develop focused docs have regressed
although our user and operator docs improved.

>