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

Dean Troyer dtroyer at gmail.com
Wed Aug 2 19:32:41 UTC 2017

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.



Dean Troyer
dtroyer at gmail.com

More information about the OpenStack-dev mailing list