Open Stack

On 10/19/2015 01:46 AM, Wan-yen Hsu wrote:
>   I fully agreed with Ramesh.  There is a need for driver owners to be
> able to quickly update their driver’s document.  Particularly, vendor's
> drivers have strong dependencies on their platform’s firmware.  For
> instance, a new release of firmware may have impact on vendor’s driver
> and may require a specific firmware settings or some workaround in
> driver configuration.  Therefore driver owners need to be able to update
> their driver documents to reflect support of firmware versions or
> hardware platforms, document firmware issues that have impacts to the
> drivers, …etc.   Also, as more and more features added to the drivers
> and some features are related, sometimes it requires restructuring of
> the document to make it easier for readers to follow and understand.  I
> would very much like to get tech writers to help my driver’s document
> but with current document review process and release schedule, it’s just
> very hard to do.  As the result, document quality suffers.  I really
> wish that we can give driver owner’s more control of their documents and
> be able to update their driver documents when needed.
>
>   Among all 3 options listed below, I prefer 2 or 3. Please consider
> these options.
>

I am neither Ironic core, nor a driver developer - however ...

>>The following are the options that I can think of to address  this:
>
>>1) Easy approvals for patches solely related to driver  documentation. Once
>
>>the driver team feels the documentation is ready, it can be  +Aed by a core
>
>>team member skipping the normal process of review. Of  course, fixing any
>
>>comments that come by, but not waiting for the normal rule  of 2x+2s.

I like this one the best. It's easy to enable and needs no extra 
bureaucracy. In fact, it's a streamlining, which I think is good.

>>2) A separate repository for driver documentation controller  by driver
>
>>developers (a bad idea ??)

If you were going to make a docs repo outside of Ironic, I'd expect it 
to be under docs, and you'd have the same concern.

>>3) Allow to push driver documentation to wiki for those who  wish to.

I'm very much not a fan of this. We have a giant system for collecting 
and publishing code and documentation. Before we punt on that and just 
use a wiki for _some_ of the documentation (now meaning that docs are in 
two places) - let's just fix the social issue around it being hard for 
vendors to update their driver docs.

>>Thoughts ???
>
>>[0]https://review.openstack.org/#/c/225602/
>
>
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>