Open Stack

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 ?




Thanks.


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
100193
--------------------------------------------------------------------------------
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
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,
Hongbin
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


-------------- 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>