<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Nov 27, 2014 at 3:47 PM, Duncan Thomas <span dir="ltr"><<a href="mailto:duncan.thomas@gmail.com" target="_blank">duncan.thomas@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div>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?<br></div></div></div></blockquote><div><br></div><div>+1 - to begin with optional seems good. We can make it mandatory or remove it if we don't see value over time.<br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><br></div>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.<br></div></div></blockquote><div><br></div><div>My proposal was to send the doc as part of  the cli patch, so the doc / screen shots will be latest<br><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><br></div>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.<br></div></blockquote><div><br></div><div>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<br><br>thanx,<br>deepak<br></div></div><br></div></div>