Open Stack

On Thu, 2019-03-28 at 07:42 -0700, Matt Riedemann wrote:
> On 3/28/2019 7:07 AM, Sean Mooney wrote:
> > when we removed the devref section of the docs
> 
> Which part of the nova docs are you referring to specifically? As far as 
> I know nothing has been removed, just re-arranged in Pike to follow a 
> standard layout, i.e. old devref stuff is probably under /reference or 
> /contributor.
they haven't been removed i just personally find it much harder to navigate
the current structure to find the developer focused docs then it was previously.
i always feel i can really write docs that are for developers only that explain
how a feature works in a level of detail that endusers should not need to know.

the cells docs https://github.com/openstack/nova/blob/stable/ocata/doc/source/cells.rst
is one example of this.
there is part of it in the admin guide https://github.com/openstack/nova/blob/stable/stein/doc/source/admin/cells.rst
there is more info in the users guide https://github.com/openstack/nova/blob/stable/stein/doc/source/user/cells.rst
and https://github.com/openstack/nova/blob/stable/stein/doc/source/user/cellsv2-layout.rst

cells are not user visable so i dont think most of that shoudl be under the user docs anyway but
that a different issue. we nolonger have a singe doc that explains how cells v2 works. and there isnt anything in
the contributor or reference folders.

granted dan and others have done lots of good presentation on cellsv2 and we have way more docs on cells i belive
then we used too so that all good but i often find my self thinking im glad we have specs to document developer
focused info on feature because we dont have an intree docs location were we capture both reason/motivation and
design constraints of a feature which is why i care alot about specs. that is what they provide that our user and
admin facing docs dont capture and shouldn't as it for a different reader.

anyway i didnt really want to rant but one of the reaons i personally dont write extensive dev docs outside
of specs besides my spelling is i dont think there really is good place for them. i might consider reference more
in the future.
>