[OpenStack-docs] Spec: Moving drivers out of openstack-manuals - documenting options
Anne Gentle
anne at openstack.org
Tue Nov 11 14:12:45 UTC 2014
On Tue, Nov 11, 2014 at 1:49 AM, Andreas Jaeger <aj at suse.com> wrote:
> On 11/09/2014 02:15 PM, Andreas Jaeger wrote:
> > As discussed in Paris, I've created a first spec to move drivers out of
> > openstack-manuals:
> > https://review.openstack.org/133372
> >
> > This still misses quite some parts and one of these is the following:
> > We currently document *all* options for a driver, so let's look at Block
> > Storage drivers:
> >
> > We have for example the table "Table 1.3. Description of Dell EqualLogic
> > volume driver configuration options" at
> >
> http://docs.openstack.org/trunk/config-reference/content/dell-equallogic-driver.html
> >
> > Should we keep these tables and structure the documentation as follows:
> >
> > Title: List of drivers
> > * Driver 1
> > * Driver 2
> >
> > Title: Configuration Options for all drivers
> > One page with all configuration options
> >
> > I see the following alternatives:
> > * Do not document these configuration options at all
> > * Use a different structure (proposals welcome)
> >
> > Please reply with your suggestions.
> >
> > Andreas
> >
>
> Tom commented in the review with:
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> See
>
> http://docs.openstack.org/trunk/config-reference/content/sheepdog-driver.html
> <-- I think something like this which has the one quick reference line
> that you need, along with the link could be useful.
> Another example (I know it's open source, but for example's sake) is
>
> http://docs.openstack.org/trunk/config-reference/content/smbfs-volume-driver.html
> <-- Imagine there's also a link in there to the vendor docs, and with
> quick reference line (which almost never changes), table of options
> automatically generated from code means no maintenance cost.
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> I like the combination of Samba and sheepdog to create "version
> independent" information:
>
> * A short paragraph explaining the driver.
> * A link for detailed instructions
> * A default paragraph like:
> Set the following in your cinder.conf, and use the following options
> to configure it.
> volume_driver=cinder.volume.drivers.smbfs.SmbfsDriver
> * And finally the autogenerated configuration options
>
>
I like this as well as a template that vendors (or projects) can then write
to. Sounds good.
> Andreas
> --
> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
> SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> GF:Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141111/289d7922/attachment.html>
More information about the OpenStack-docs
mailing list