
<html><body><p>I prefer option 1 with 3, which is easy to maintain. and also accounting for user experience.<br>for option 2, is it really good to expose helpful message in API layer ?<br><br><br><br><br>Thanks.<br><br><br>Best Wishes,<br>--------------------------------------------------------------------------------<br>Kai Qiang Wu (吴开强  Kennan）<br>IBM China System and Technology Lab, Beijing<br><br>E-mail: wkqwu@cn.ibm.com<br>Tel: 86-10-82451647<br>Address: Building 28(Ring Building), ZhongGuanCun Software Park,  <br>         No.8 Dong Bei Wang West Road, Haidian District Beijing P.R.China 100193<br>--------------------------------------------------------------------------------<br>Follow your heart. You are miracle! <br><br><img width="16" height="16" src="cid:1__=8FBBF522DFA6F05D8f9e8a93df938690918c8FB@" border="0" alt="Inactive hide details for Hongbin Lu ---12/05/2016 03:53:56 am---Hi all, This is a continued discussion from the last team meet"><font color="#424282">Hongbin Lu ---12/05/2016 03:53:56 am---Hi all, This is a continued discussion from the last team meeting. For recap, 'labels' is a property</font><br><br><font size="2" color="#5F5F5F">From:        </font><font size="2">Hongbin Lu <hongbin.lu@huawei.com></font><br><font size="2" color="#5F5F5F">To:        </font><font size="2">"OpenStack Development Mailing List (not for usage questions)" <openstack-dev@lists.openstack.org></font><br><font size="2" color="#5F5F5F">Cc:        </font><font size="2">Qun XK Wang/China/IBM@IBMCN</font><br><font size="2" color="#5F5F5F">Date:        </font><font size="2">12/05/2016 03:53 am</font><br><font size="2" color="#5F5F5F">Subject:        </font><font size="2">[openstack-dev] [magnum] How to document 'labels'</font><br><hr width="100%" size="2" align="left" noshade style="color:#8091A5; "><br><br><br><font color="#1F497D" face="Calibri">Hi all,</font><br><font color="#1F497D" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">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:</font><ul><ul><font color="#1F497D" face="Calibri">1.       Place the documentation in Magnum CLI as help text (as Wangqun proposed [1][2]).</font><br><font color="#1F497D" face="Calibri">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.</font><br><font color="#1F497D" face="Calibri">3.       Place the documentation in a documentation server (like developer.openstack.org/…), and add the doc link to the CLI help text.</font></ul></ul><font color="#1F497D" face="Calibri">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?</font><br><font color="#1F497D" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">[1] </font><a href="https://review.openstack.org/#/c/307631/"><u><font color="#0000FF" face="Calibri">https://review.openstack.org/#/c/307631/</font></u></a><br><font color="#1F497D" face="Calibri">[2] </font><a href="https://review.openstack.org/#/c/307642/"><u><font color="#0000FF" face="Calibri">https://review.openstack.org/#/c/307642/</font></u></a><br><font color="#1F497D" face="Calibri"> </font><br><font color="#1F497D" face="Calibri">Best regards,</font><br><font color="#1F497D" face="Calibri">Hongbin</font><tt>__________________________________________________________________________<br>OpenStack Development Mailing List (not for usage questions)<br>Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe<br></tt><tt><a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a></tt><tt><br></tt><br><br><BR>


</body></html>