Open Stack

On 12/09/2014 04:11 PM,  by wrote:
>>>[vad] how about the documentation in this case?... bcos it needs some
> place to document (a short desc and a link to vendor page) or list these
> kind of out-of-tree plugins/drivers...  just to make the user aware of
> the availability of such plugins/driers which is compatible with so and
> so openstack release.  
> I checked with the documentation team and according to them, only the
> following plugins/drivers only will get documented...
> 1) in-tree plugins/drivers (full documentation) 
> 2) third-party plugins/drivers (ie, one implements and follows this new
> proposal, a.k.a partially-in-tree due to the integration module/code)...
> 
> *** no listing/mention about such completely out-of-tree plugins/drivers***

Discoverability of documentation is a serious issue. As I commented on
docs spec [1], I think there are already too many places, mini-sites and
random pages holding information that is relevant to users. We should
make an effort to keep things discoverable, even if not maintained
necessarily by the same, single team.

I think the docs team means that they are not able to guarantee
documentation for third-party *themselves* (and has not been able, too).
The docs team is already overworked as it is now, they can't take on
more responsibilities.

So once Neutron's code will be split, documentation for the users of all
third-party modules should find a good place to live in, indexed and
searchable together where the rest of the docs are. I'm hoping that we
can find a place (ideally under docs.openstack.org?) where third-party
documentation can live and be maintained by the teams responsible for
the code, too.

Thoughts?

/stef

[1] https://review.openstack.org/#/c/133372/