<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Dec 16, 2014 at 4:05 AM, Neil Jerram <span dir="ltr"><<a href="mailto:Neil.Jerram@metaswitch.com" target="_blank">Neil.Jerram@metaswitch.com</a>></span> wrote:<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class=""><div class="h5">Stefano Maffulli <<a href="mailto:stefano@openstack.org">stefano@openstack.org</a>> writes:<br>
<br>
> On 12/09/2014 04:11 PM,  by wrote:<br>
>>>>[vad] how about the documentation in this case?... bcos it needs some<br>
>> place to document (a short desc and a link to vendor page) or list these<br>
>> kind of out-of-tree plugins/drivers...  just to make the user aware of<br>
>> the availability of such plugins/driers which is compatible with so and<br>
>> so openstack release.<br>
>> I checked with the documentation team and according to them, only the<br>
>> following plugins/drivers only will get documented...<br>
>> 1) in-tree plugins/drivers (full documentation)<br>
>> 2) third-party plugins/drivers (ie, one implements and follows this new<br>
>> proposal, a.k.a partially-in-tree due to the integration module/code)...<br>
>><br>
>> *** no listing/mention about such completely out-of-tree plugins/drivers***<br>
><br>
> Discoverability of documentation is a serious issue. As I commented on<br>
> docs spec [1], I think there are already too many places, mini-sites and<br>
> random pages holding information that is relevant to users. We should<br>
> make an effort to keep things discoverable, even if not maintained<br>
> necessarily by the same, single team.<br>
><br>
> I think the docs team means that they are not able to guarantee<br>
> documentation for third-party *themselves* (and has not been able, too).<br>
> The docs team is already overworked as it is now, they can't take on<br>
> more responsibilities.<br>
><br>
> So once Neutron's code will be split, documentation for the users of all<br>
> third-party modules should find a good place to live in, indexed and<br>
> searchable together where the rest of the docs are. I'm hoping that we<br>
> can find a place (ideally under <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a>?) where third-party<br>
> documentation can live and be maintained by the teams responsible for<br>
> the code, too.<br>
><br>
> Thoughts?<br>
<br>
</div></div>I suggest a simple table, under <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a>, where each row has<br>
the plugin/driver name, and then links to the documentation and code.<br>
There should ideally be a very lightweight process for vendors to add<br>
their row(s) to this table, and to edit those rows.<br>
<br>
I don't think it makes sense for the vendor documentation itself to be<br>
under <a href="http://docs.openstack.org" target="_blank">docs.openstack.org</a>, while the code is out of tree.<br>
<br></blockquote><div><br></div><div>Stef has suggested <a href="http://docs.openstack.org/third-party">docs.openstack.org/third-party</a> as a potential location on the review at <span style="font-size:12.7272720336914px;color:rgb(80,0,80)">[1] </span><a href="https://review.openstack.org/#/c/133372/" target="_blank" style="font-size:12.7272720336914px">https://review.openstack.org/#/c/133372/</a>. </div><div><br></div><div>The proposal currently is that the list's source would be in the openstack-manuals repository, and the process for adding to that repo is the same as all OpenStack contributions. </div><div><br></div><div>I plan to finalize the plan in January, thanks all for the input, and keep it coming.</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Regards,<br>
        Neil<br>
<div class=""><div class="h5"><br>
<br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div></div></div>