Open Stack

On Thu, Nov 27, 2014 at 3:47 PM, Duncan Thomas <duncan.thomas at gmail.com>
wrote:

> 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

thanx,
deepak
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141128/621ed8c4/attachment.html>