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: wk...@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...@huawei.com>
To: "OpenStack Development Mailing List (not for usage questions)"
<openstack-dev@lists.openstack.org>
Cc: Qun XK Wang/China/IBM@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
