Open Stack

On 08/02/2017 08:53 PM, Ghanshyam Mann wrote:
> On Thu, Aug 3, 2017 at 1:20 AM, Doug Hellmann <doug at doughellmann.com> wrote:
>> Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:
>>> 2017-08-03 0:52 GMT+09:00 Doug Hellmann <doug at doughellmann.com>:
>>>> Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:
>>>>> On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
>>>>>> On 08/02/2017 09:22 AM, Stephen Finucane wrote:
>>>>>>> On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
>>>>>>>> 3. The patch for the import of the admin guide [8] is missing some CLI
>>>>>>>> specific pages which are pretty useful given they aren't documented
>>>>>>>> anywhere else, like the forced_host part of the compute API [9].
>>>>>>>> Basically anything that's cli-nova-* in the admin guide should be in the
>>>>>>>> Nova docs. It's also missing the compute-flavors page [10] which is
>>>>>>>> pretty important for using OpenStack at all.
>>>>>>>
>>>>>>> This is a tricky one. Based on previous discussions with dhellmann, the
>>>>>>> plan
>>>>>>> seems to be to replace any references to 'nova xxx' or 'openstack xxx'
>>>>>>> commands
>>>>>>> (i.e. commands using python-novaclient or python-openstackclient) in favour
>>>>>>> of
>>>>>>> 'curl'-based requests. The idea here is that the Python clients are not the
>>>>>>> only clients available, and we shouldn't be "mandating" their use by
>>>>>>> referencing them in the docs. I get this, though I don't fully agree with
>>>>>>> it
>>>>>>> (who really uses curl?)
>>>>>>
>>>>>> Are we going to document the python clients elsewhere then?
>>>>>
>>>>> I think the docs would go into the respective python clients docs?
>>>>
>>>> Right. I don't remember the details of the curl discussion, but I
>>>> think what I was trying to say there was that the "nova" command
>>>> line tool installed via python-novaclient should be documented as
>>>> part of the openstack/python-novaclient repo rather than openstack/nova.
>>>> A CLI reference for nova-manage, which I think is in openstack/nova,
>>>> could be documented in openstack/nova.
>>>>
>>>> Basically, put the docs with the code, which is the whole point of this
>>>> migration.
>>>
>>> It is true for CLI reference.
>>> The gray zone is CLI stuffs in the admin guide and/or end-user guide.
>>> I think this is the point Matt raised.
>>> cli-nova-* stuffs in the admin guide was per topic like launching instance,
>>> migrating instances and so on. It is actually beyond the CLI reference to me.
>>> It is about how to use specific features of nova.
>>> IMHO this kind of stuffs can be covered by the admin guide or user guide,
>>> so it fits into openstack/nova (or other server projects).
>>
>> Yeah, I don't know.
>>
>> 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).
>>
>> 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.
> 
> This is nice point. If nova going to have those doc(using cli), it
> could be confusing for new folks about using novaclient/osc commands.
> They might have installed python-novaclient and try to use "openstack
> server create" because Nova doc says. Or it can be other client over
> nova APIs.
> 
> Also there is chance that Nova might have some obsolete doc (till
> someone use those and report bug)  if any command changed (very rare)
> or some param going to remove with deprecated process.
> 
> IMO, Nova doc should talk about more conceptual or operation things
> and then give reference to CLI doc as example.
> For example:
> "Launch VM doc in Nova" tells about all precondition to launch VM and
> APIs (it can be API name or API ref or Curl example) to get required
> data and launch VM and at the end give reference to CLI (novaclient or
> osc) doc where set of CLI are shown for that operation. If no CLI doc
> exist for particular operation, then nova doc still holds good
> information of doing that using APIs.

This is about audience and usage. We have the following audience and users:

* CLI users (nova cli or openstack client)
* Horizon users
* API users (possibly using python APIs, possibly others)

When a person shows up at our site from where ever, we should assume
they are a CLI user. It's universal, and easy to show examples. It's
also just simpler to integrate these examples then it is to integrate
Horizon usage.

API users aren't going to be reading the using nova guide, they are
going to be deep in the API ref, and be looking for their examples
there. We shouldn't be putting API examples in line in the admin or user
guides. It's fine and good to reference that Nova is API driven, but
again, you present curl commands to users that are just trying to learn
the system, and you've lost them.

The other important point about documentation, is that duplication of
content is not a sin. It's fine and good to have then entire clear set
of steps needed in one place without having to chase back references.
It's totally fine if "how to start a server" is content complete in the
Nova doc, and the openstack client doc, and the nova cli doc.

The boundaries that we draw around these in our head are because after
years of use, we think about things in certain buckets, but for a new
user finding our stuff on google, they don't have those buckets.

	-Sean

-- 
Sean Dague
http://dague.net