Open Stack

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 <dpkshetty at gmail.com> 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
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Kind Regards
Valeriy Ponomaryov
www.mirantis.com
vponomaryov at mirantis.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141126/0cef0e2a/attachment.html>