<div dir="ltr"><div>Hi Deepak,</div><div><br></div><div>Docs are present in any project already, according to example with manila - <a href="https://github.com/openstack/manila/tree/master/doc/source">https://github.com/openstack/manila/tree/master/doc/source</a></div><div><br></div><div>It is used for docs on <a href="http://docs.openstack.org/">http://docs.openstack.org/</a> , also everyone if able to contribute to it.</div><div><br></div><div>See docs built on basis of files from manila repo: <a href="http://docs.openstack.org/developer/manila/">http://docs.openstack.org/developer/manila/</a></div><div><br></div><div>For most of projects we have already useful resource: <a href="http://docs.openstack.org/cli-reference/content/">http://docs.openstack.org/cli-reference/content/</a></div><div><br></div><div>In conclusion I can say that it is question more to the organization of creation such docs than possibility to create it in general.</div><div><br></div><div>Regards,</div><div>Valeriy Ponomaryov</div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Nov 26, 2014 at 8:01 AM, Deepak Shetty <span dir="ltr"><<a href="mailto:dpkshetty@gmail.com" target="_blank">dpkshetty@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div>Hi stackers,<br></div> I was having this thought which i believe applies to all projects of openstack (Hence All in the subject tag)<br><br></div>My proposal is to have examples or usecase folder in each project which has info on how to use the feature/enhancement (which was submitted as part of a gerrit patch)<br></div><div>In short, a description with screen shots (cli, not GUI) which should be submitted (optionally or mandatory) along with patch (liek how testcases are now enforced)<br></div><div><br></div>I would like to take an example to explain. Take this patch @ <a href="https://review.openstack.org/#/c/127587/" target="_blank">https://review.openstack.org/#/c/127587/</a> which adds a default volume type in Manila<br><br></div>Now it would have been good if we could have a .txt or .md file alogn with the patch that explains :<br><br></div>1) What changes are needed in manila.conf to make this work<br></div><br>2) How to use the cli with this change incorporated<br></div><br>3) Some screen shots of actual usage (Now the author/submitted would have tested in devstack before sending patch, so just copying those cli screen shots wouldn't be too big of a deal)<br></div><br>4) Any caution/caveats that one has to keep in mind while using this<br><br>It can be argued that some of the above is satisfied via commit msg and lookign at test cases.<br>But i personally feel that those still doesn't give a good visualization of how a feature patch works in reality<br><br></div>Adding such a example/usecase file along with patch helps in multiple ways:<br><br></div>1) It helps the reviewer get a good picture of how/which clis are affected and how this patch fits in the flow<br></div><br>2) It helps documentor get a good view of how this patch adds value, hence can document it better<br></div><br>3) It may help the author or anyone else write a good detailed blog post using the examples/usecase as a reference<br></div><br>4) Since this becomes part of the patch and hence git log, if the feature/cli/flow changes in future, we can always refer to how the feature was designed, worked when it was first posted by looking at the example usecase<br></div><br>5) It helps add a lot of clarity to the patch, since we know how the author tested it and someone can point missing flows or issues (which otherwise now has to be visualised)<br></div><br>6) I feel this will help attract more reviewers to the patch, since now its more clear what this patch affects, how it affects and how flows are changing, even a novice reviewer can feel more comfortable and be confident to provide comments.<br><br></div>Thoughts ?<br><br>thanx,<br>deepak<br><br></div>
<br>_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature"><div dir="ltr">Kind Regards<br>Valeriy Ponomaryov<br><a href="http://www.mirantis.com" target="_blank">www.mirantis.com</a><br><a href="mailto:vponomaryov@mirantis.com" target="_blank">vponomaryov@mirantis.com</a><br></div></div>
</div></div>