[openstack-dev] [nova][docs] Concerns with docs migration

Sean Dague sean at dague.net
Thu Aug 3 09:34:34 UTC 2017

On 08/02/2017 03:32 PM, Dean Troyer wrote:
> On Wed, Aug 2, 2017 at 11:20 AM, Doug Hellmann <doug at doughellmann.com> wrote:
>> My gut response is to say that if the example uses nova-manage or
>> one of the nova service executables, then that makes sense to leave
>> in the nova tree, but otherwise it should go into either the
>> python-novaclient or python-openstackclient repositories (depending
>> on which command line tool is used in the example).
> I don't think this is a good rule of thumb...
>> On the other hand, I can see that being somewhat confusing for
>> someone who lands at the nova docs and can't find instructions for
>> how to use it. Maybe less confusing, though, than if I am not
>> *running* nova but am trying to use a nova deployed by someone else
>> and I start from the python-novaclient or python-openstackclient
>> docs because I installed one of those in order to talk to nova.
> When the point of the example is to illustrate configuring nova, the
> example should stay with the nova code, even if it uses novaclient or
> osc.  The examples that are about _using_ novaclient or osc belong in
> those repos, but where they are just a means to configuring something
> in nova, they should remain with nova and use the tools that users are
> expected to be familiar with (novaclient and/or osc in this example).
>> I thought "put the docs with the code" would be a simple enough
>> rule that we wouldn't have to think too hard about where to put
>> individual example files, which would speed up the migration.
> If I find a doc that tells me how to set up a VM with a Neutron
> network and ports and subnets and floating IPs that uses curl, I'm not
> reading farther.

++ that is actually kind of a punch in the face to our users


Sean Dague

More information about the OpenStack-dev mailing list