Hi Deepak, Docs are present in any project already, according to example with manila - https://github.com/openstack/manila/tree/master/doc/source
It is used for docs on http://docs.openstack.org/ , also everyone if able to contribute to it. See docs built on basis of files from manila repo: http://docs.openstack.org/developer/manila/ For most of projects we have already useful resource: http://docs.openstack.org/cli-reference/content/ In conclusion I can say that it is question more to the organization of creation such docs than possibility to create it in general. Regards, Valeriy Ponomaryov On Wed, Nov 26, 2014 at 8:01 AM, Deepak Shetty <[email protected]> wrote: > Hi stackers, > I was having this thought which i believe applies to all projects of > openstack (Hence All in the subject tag) > > 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) > 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) > > I would like to take an example to explain. Take this patch @ > https://review.openstack.org/#/c/127587/ which adds a default volume type > in Manila > > Now it would have been good if we could have a .txt or .md file alogn with > the patch that explains : > > 1) What changes are needed in manila.conf to make this work > > 2) How to use the cli with this change incorporated > > 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) > > 4) Any caution/caveats that one has to keep in mind while using this > > It can be argued that some of the above is satisfied via commit msg and > lookign at test cases. > But i personally feel that those still doesn't give a good visualization > of how a feature patch works in reality > > Adding such a example/usecase file along with patch helps in multiple ways: > > 1) It helps the reviewer get a good picture of how/which clis are affected > and how this patch fits in the flow > > 2) It helps documentor get a good view of how this patch adds value, hence > can document it better > > 3) It may help the author or anyone else write a good detailed blog post > using the examples/usecase as a reference > > 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 > > 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) > > 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. > > Thoughts ? > > thanx, > deepak > > > _______________________________________________ > OpenStack-dev mailing list > [email protected] > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev > > -- Kind Regards Valeriy Ponomaryov www.mirantis.com [email protected]
_______________________________________________ OpenStack-dev mailing list [email protected] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
