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

Kai Qiang Wu wkqwu at cn.ibm.com
Thu May 12 10:12:15 UTC 2016

I prefer option 1 with 3, which is easy to maintain. and also accounting
for user experience.
for option 2, is it really good to expose helpful message in API layer ?


Best Wishes,
Kai Qiang Wu (吴开强  Kennan)
IBM China System and Technology Lab, Beijing

E-mail: wkqwu at cn.ibm.com
Tel: 86-10-82451647
Address: Building 28(Ring Building), ZhongGuanCun Software Park,
         No.8 Dong Bei Wang West Road, Haidian District Beijing P.R.China
Follow your heart. You are miracle!

From:	Hongbin Lu <hongbin.lu at huawei.com>
To:	"OpenStack Development Mailing List (not for usage questions)"
            <openstack-dev at lists.openstack.org>
Cc:	Qun XK Wang/China/IBM at IBMCN
Date:	12/05/2016 03:53 am
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
      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
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,
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/935f7d6e/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: graycol.gif
Type: image/gif
Size: 105 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160512/935f7d6e/attachment.gif>

More information about the OpenStack-dev mailing list