[openstack-dev] [magnum] How to document 'labels'

Tim Bell Tim.Bell at cern.ch
Thu May 12 16:57:53 UTC 2016

I’d be in favor of 1.

At the end of the man page or full help text, a URL could be useful for more information but since most people using the CLI will have to do a context change to access the docs, it is not a simple click but a copy/paste/find the browser window which is not so friendly.


From: Jamie Hannaford <jamie.hannaford at rackspace.com>
Reply-To: "OpenStack Development Mailing List (not for usage questions)" <openstack-dev at lists.openstack.org>
Date: Thursday 12 May 2016 at 16:04
To: "OpenStack Development Mailing List (not for usage questions)" <openstack-dev at lists.openstack.org>
Cc: Qun XK Wang <bjwqun at cn.ibm.com>
Subject: Re: [openstack-dev] [magnum] How to document 'labels'

+1 for 1 and 3.

I'm not sure maintainability should discourage us from exposing information to the user through the client - we'll face the same maintenance burden as we currently do, and IMO it's our job as a team to ensure our docs are up-to-date. Any kind of input which touches the API should also live in the API docs, because that's in line with every other OpenStack service.

I don't think I've seen documentation exposed via the API before (#2). I think it's a lot of work too, and I don't see what benefit it provides.


From: Hongbin Lu <hongbin.lu at huawei.com>
Sent: 11 May 2016 21:52
To: OpenStack Development Mailing List (not for usage questions)
Cc: Qun XK Wang
Subject: [openstack-dev] [magnum] How to document 'labels'

Hi all,

This is a continued discussion from the last team meeting. For recap, ‘labels’ is a property in baymodel and is used by users to input additional key-pair pairs to configure the bay. In the last team meeting, we discussed what is the best way to document ‘labels’. In general, I heard three options:

1.       Place the documentation in Magnum CLI as help text (as Wangqun proposed [1][2]).

2.       Place the documentation in Magnum server and expose them via the REST API. Then, have the CLI to load help text of individual properties from Magnum server.

3.       Place the documentation in a documentation server (like developer.openstack.org/…), and add the doc link to the CLI help text.
For option #1, I think an advantage is that it is close to end-users, thus providing a better user experience. In contrast, Tom Cammann pointed out a disadvantage that the CLI help text might be easier to become out of date. For option #2, it should work but incurs a lot of extra work. For option #3, the disadvantage is the user experience (since user need to click the link to see the documents) but it makes us easier to maintain. I am thinking if it is possible to have a combination of #1 and #3. Thoughts?

[1] https://review.openstack.org/#/c/307631/
[2] https://review.openstack.org/#/c/307642/

Best regards,

Rackspace International GmbH a company registered in the Canton of Zurich, Switzerland (company identification number CH- whose registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland. Rackspace International GmbH privacy policy can be viewed at www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may contain confidential or privileged information intended for the recipient. Any dissemination, distribution or copying of the enclosed material is prohibited. If you receive this transmission in error, please notify us immediately by e-mail at abuse at rackspace.com and delete the original message. Your cooperation is appreciated.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/170d089e/attachment.html>

More information about the OpenStack-dev mailing list