On Thu, Nov 27, 2014 at 3:47 PM, Duncan Thomas <duncan.tho...@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

OpenStack-dev mailing list

Reply via email to