[openstack-dev] [Ironic] Driver documentation in Ironic
mordred at inaugust.com
Mon Oct 19 13:20:34 UTC 2015
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.
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
More information about the OpenStack-dev