Open Stack

Stefano Maffulli <stefano at openstack.org> writes:

> 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?

I suggest a simple table, under docs.openstack.org, where each row has
the plugin/driver name, and then links to the documentation and code.
There should ideally be a very lightweight process for vendors to add
their row(s) to this table, and to edit those rows.

I don't think it makes sense for the vendor documentation itself to be
under docs.openstack.org, while the code is out of tree.

Regards,
        Neil