[openstack-dev] [All] Proposal to add examples/usecase as part of new features / cli / functionality patches
dpkshetty at gmail.com
Fri Nov 28 06:18:41 UTC 2014
On Thu, Nov 27, 2014 at 3:47 PM, Duncan Thomas <duncan.thomas at gmail.com>
> I'm not sure about making it mandatory, but I can certainly see the
> benefits of doing this in some cases. Maybe we can start by creating the
> area and making the doc optional, and allow reviews to ask for it to be
> added where they consider it useful?
+1 - to begin with optional seems good. We can make it mandatory or remove
it if we don't see value over time.
> Sometimes (often in cinder), a feature gets written well before the
> cinder-cli part gets written, but I guess you can still document via curl
> or whatever testing mechanism you used - a separate patch can improve the
> doc later once the cli part is written.
My proposal was to send the doc as part of the cli patch, so the doc /
screen shots will be latest
> My one big worry, as with all documentation, is that we'll end up with a
> large amount of stale documentation and nobody motivated to fix it.
If the doc is part of the patch that adds the feature/functionality, there
will be less chance of it being stale. Yes if someone changed/modified the
way it works, it will be thru some other patch, so the doc accompanying
that patch should modify the existing doc and not create a new one. I can
see here that we may have issues on how to figure which doc maps to which
patch/functionality as the docs added grows over time
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev