<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Oct 30, 2013 at 8:02 AM, Lorin Hochstein <span dir="ltr"><<a href="mailto:lorin@nimbisservices.com" target="_blank">lorin@nimbisservices.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">Hi Anne:<div><br></div><div>Gotcha. Has there been any discussion about what to do with the python-*client sites? We have a bunch of them, and they aren't very consistent in quality (or even css theming!). I don't even know what triggers an update to these, if it's on commit to the client repository or only when new point versions are released to pypi, or some other event.</div>
</div></blockquote><div><br></div><div>I'm fairly certain the source lives in doc/source in each repo:</div><div><br></div><div><a href="https://github.com/openstack/python-novaclient/tree/master/doc/source">https://github.com/openstack/python-novaclient/tree/master/doc/source</a><br>
</div><div><br></div><div>If you look at <a href="https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/openstack-publish-jobs.yaml">https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/openstack-publish-jobs.yaml</a> you see the jobs to build those. Pretty sure they're triggered on commit. It's just that no one has done real doc work on those. It'd be great if you are up for it.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">
<div><br></div><div>They're potentially a good place to serve as SDK reference because of Sphinx auto-doc. I'm interested in working on cleaning these up, maybe using the keystoneclient site as the reference since it's OpenStack themed <<a href="http://docs.openstack.org/developer/python-keystoneclient/" target="_blank">http://docs.openstack.org/developer/python-keystoneclient/</a>>.</div>
<div><br></div><div>Is this going to be discussed at the SDK session at the summit? (Alas I won't be there).</div></div></blockquote><div><br></div><div>I'll make sure we do, it's a recurring theme release after release that those sites are mostly ignored. Thanks for bringing it up.</div>
<div><br></div><div>I also have a hunch (seriously, just a guess) that for a long while people were just hoping that openstackclient would take over and the individual docs wouldn't have to be maintained? What do you think about that possibility?</div>
<div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">
<div>
<br></div><div><br></div><div>We have a whole bunch of sites:</div><div><br></div><div>* <a href="http://docs.openstack.org/developer/python-novaclient/" target="_blank">http://docs.openstack.org/developer/python-novaclient/</a></div>
<div>* <a href="http://docs.openstack.org/developer/python-keystoneclient/" target="_blank">http://docs.openstack.org/developer/python-keystoneclient/</a></div><div>* <a href="http://docs.openstack.org/developer/python-cinderclient/" target="_blank">http://docs.openstack.org/developer/python-cinderclient/</a></div>
<div>* <a href="http://docs.openstack.org/developer/python-swiftclient/" target="_blank">http://docs.openstack.org/developer/python-swiftclient/</a></div><div>* <a href="http://docs.openstack.org/developer/python-glanceclient/" target="_blank">http://docs.openstack.org/developer/python-glanceclient/</a></div>
<div>* <a href="http://docs.openstack.org/developer/python-neutronclient/" target="_blank">http://docs.openstack.org/developer/python-neutronclient/</a></div><div>* <a href="http://docs.openstack.org/developer/python-heatclient/" target="_blank">http://docs.openstack.org/developer/python-heatclient/</a></div>
<div>* <a href="http://docs.openstack.org/developer/python-ceilometerclient/" target="_blank">http://docs.openstack.org/developer/python-ceilometerclient/</a></div><div>* <a href="http://docs.openstack.org/developer/python-openstackclient/" target="_blank">http://docs.openstack.org/developer/python-openstackclient/</a></div>
<span class=""><font color="#888888">
<div><br></div></font></span><div><span class=""><font color="#888888"><br></font></span><div class="gmail_extra"><span class=""><font color="#888888">Lorin</font></span><div><div class="h5"><br><br><div class="gmail_quote">
On Wed, Oct 30, 2013 at 8:51 AM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">
<div>On Tue, Oct 29, 2013 at 9:06 PM, Lorin Hochstein <span dir="ltr"><<a href="mailto:lorin@nimbisservices.com" target="_blank">lorin@nimbisservices.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">All:<div><br></div><div>For the RST conversion, are you also going to be targeting the python-*client documentation that currently exists (e.g., python-novaclient, python-swiftclient, ...)?</div>
<div><br></div></div></blockquote><div><br></div></div><div>Hi Lorin, </div><div><br></div><div>Only hand-edited RST files from the 6 core projects are in the scope as far as I know. </div><div><br></div><div>Anne</div><div>
<div><div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div></div>
<div>Lorin</div></div><div class="gmail_extra"><br><br><div class="gmail_quote"><div><div>On Tue, Oct 29, 2013 at 5:22 PM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div><div><div dir="ltr">Hi again everyone, <div>
<br><div>Nermina, Sean and I spoke today and Sean's going to modify his blueprint and start with a patch that contains the conversion tool plus just the RST files for cinder, to be placed in doc/training-guide. He'll show the placement in the associates guide so reviewers can see the end-goal as well as the steps prior to the training guide update. Nermina can take a look at what could be incorporated into other guides.</div>
<div><br></div><div>I hope this is a good step forward to get some proof of concept content in there so reviewers can take a look and offer suggestions. </div><div><br></div><div>Thanks,</div><div>Anne</div></div></div><div class="gmail_extra">
<div><div>
<br><br><div class="gmail_quote">On Mon, Oct 28, 2013 at 7:45 PM, Nermina Miller <span dir="ltr"><<a href="mailto:nerminamiller@gmail.com" target="_blank">nerminamiller@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr">Hello everyone,<div><br></div><div>I've reviewed the training docs and spoke to Sean today, and here is a proposed solution for inclusion of the devref files converted from rst:</div><div><br></div><div>
<b>Immediate Steps/First Patch</b></div><div>- Submit the Associates Guide with xi:inclusions of the 30 relevant devref files (and appropriate updated xi:includes from the other guides)</div><div>- Add the entire batch of the devref files to the Common folder (subfolder Training) so the files can be made available to the other guides in the long term. (Why all? Because the py script updates and converts them ALL at the same time. You may already know this but it helps to explain the need for such a large batch.) </div>
<div><br></div><div><b>NOTE:</b> Andreas, Sean may ask you for help to figure out the best commit procedure considering that the training guides may need to be made available for other releases besides Havana. (I've shared the latest backporting steps with Sean.) </div>
<div><br></div><div><b>IMPORTANT:</b> Hold off on the editing of rst converts until Sean's team publishes an appropriate procedure for that. All of the devref xml files have to be edited in the native rst format and then automatically converted with the script that will be stored in Common. Once the guide is merged, you can begin making comments and editing the files using the said procedure. (Sean said he would add it to the How To wiki.) Understand that this is a work in progress that needs the community's feedback through bug logs and fixes. That also means it would be incredibly helpful to add the training guides to the OpenStack docs index along with Disqus and Launchpad links.</div>
<div><br></div><div><b>Further Steps</b></div><div>- Add each of the remaining training guides with the appropriate xi:includes to the devref files in Common</div><div>- Transition to the xml format so a wider audience can edit the files and for easier updates (and to eliminate the need for conversion). Also, align those docs with the OpenStack docs file naming and other conventions.</div>
<div> <br><div>Sean is planning to submit the first patch tomorrow. It would be great to have at least one guide to showcase in Hong Kong, and I believe we need to help Sean make that happen so the training group can begin receiving feedback and growing their guides live. </div>
<div><br></div><div>Thank you, Sean! Please correct or add to any of the information listed here. And, thank you, all for considering these points.</div><span><font color="#888888"><div><br></div><div>Nermina</div>
</font></span><div><div><div class="gmail_extra"><br><br><div class="gmail_quote">
On Mon, Oct 21, 2013 at 8:52 PM, Nermina Miller <span dir="ltr"><<a href="mailto:nerminamiller@gmail.com" target="_blank">nerminamiller@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr">No problem, Anne. Colin, if this is the missing batch, where is the rest of the guide? Also, do you have a blueprint or a proposed ToC I can take a look at? Please brief me on the history of training docs a little. Thanks much! - Nermina</div>
<div><div>
<div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Oct 21, 2013 at 7:52 PM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">
<div>On Mon, Oct 21, 2013 at 6:43 PM, Nermina Miller <span dir="ltr"><<a href="mailto:nerminamiller@gmail.com" target="_blank">nerminamiller@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Anne and Colin, <span></span>I'd be happy to help with content management and migration. -Nermina <div>
<br></div></blockquote><div><br></div></div><div>Awesome, Nermina! I think you'll find a list of content they found missing at </div><div><a href="https://review.openstack.org/#/c/50509/1" target="_blank">https://review.openstack.org/#/c/50509/1</a></div>
<div> </div><div>And someone do tell me if I'm being crazy in taking on more conceptual doc that we might not be able to maintain. I trust you all!</div><div><br></div><div>Thanks, </div><div><br></div><div>Anne</div>
<div><div>
<div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div><br>On Monday, October 21, 2013, Anne Gentle wrote:<br>
</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><br><div class="gmail_extra"><div><br><br><div class="gmail_quote">On Thu, Oct 10, 2013 at 12:02 PM, Colin McNamara <span dir="ltr"><<a>colin@2cups.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word">I absolutely believe that the appropriate role is to improve the source documentation. Right now I'm just riding a find line between improving and duplicating. My focus has been on getting the structure of training-guides through included content, and then when we get to our alpha to focus on improving the referenced content. <div>
<br></div><div>A direct example of that would on the administrative section that references the user-guide content. There are items in there that could benefit from visual representation of the steps noted. My goal is to get the included content roughed out in the training-guide, and then engage the user group contributors that we have been building to do things like create visual representations of configuration steps that are unclear. </div>
<div><br></div><div>So, to be very clear. My goals are to improve the source documentation. My suggested method is to focus on xi:inclusion as much as possible within training-guides. This drives the improvement in content to the sources that are referenced, vs creating yet another external operations guide that won't be able to map to the six month release schedule.</div>
</div></blockquote><div><br></div><div><br></div><div>Circling back to take a closer look now that the release is out. </div><div><br></div><div>I like your main goal of improving the source documentation. But RST documentation isn't great source since it can't be xi:included, it gets hung up in reviews for a long time, it's not well maintained, I'm just not sure you want to use it as your source. I'm trying to help you avoid a pitfall here. :) </div>
<div><br></div><div>So far the data shows that the dev docs are less maintained, when we bring them in to openstack-manuals they tend to improve at a faster rate. I could go through your review a file at a time and tell you where the info should go, but I can't make it a priority myself right now. Is there anyone else you can identify to help you with content placement? I'd also recommend a file at a time to help reviewers review your patches. Or a project at a time. Some way of helping reviewers see the whole deliverable will help reviewers.</div>
<div><br></div><div>Anyone else want to add to the discussion? Feel free to add RST-as-source to tomorrow's doc team meeting agenda at <a href="https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting" target="_blank">https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting</a>. </div>
<div><br></div><div>Anne</div><div><br></div><div> </div><blockquote style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div style="word-wrap:break-word">
<div><div><div><div>
<div style="text-indent:0px;letter-spacing:normal;font-variant:normal;text-align:-webkit-auto;font-style:normal;font-weight:normal;line-height:normal;text-transform:none;font-size:medium;white-space:normal;font-family:Helvetica;word-wrap:break-word;word-spacing:0px">
<div style="font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:-webkit-auto;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;word-wrap:break-word">
<div style="font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:normal;line-height:normal;text-align:-webkit-auto;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;word-wrap:break-word">
<div style="font-style:normal;font-variant:normal;letter-spacing:normal;line-height:normal;text-align:-webkit-auto;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;word-wrap:break-word"><div style="font-style:normal;font-variant:normal;letter-spacing:normal;line-height:normal;text-align:-webkit-auto;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;word-wrap:break-word">
<p style="font-size:medium;font-family:Helvetica;font-weight:normal">Regards,</p><p style="font-size:medium;font-family:Helvetica;font-weight:normal">Colin</p><div style="font-size:medium;font-family:Helvetica;font-weight:normal">
<b style="font-family:Calibri,sans-serif;font-size:15px"><span style="font-size:12pt;color:navy;font-family:Arial,sans-serif">Colin McNamara</span></b><br></div><div style="font-size:medium;font-family:Helvetica"><span style="font-family:Calibri,sans-serif;font-size:15px"><span style="font-size:12pt;color:navy;font-family:Arial,sans-serif">People | Process | Technology</span></span></div>
<div><font color="#000080" face="Arial, sans-serif"><span style="font-size:16px">--------------------------------------------</span></font></div><div style="font-size:medium;font-family:Helvetica;font-weight:normal"><div style="font-family:Calibri,sans-serif;font-size:11pt;margin:0in 0in 0.0001pt">
<b><span style="font-size:10pt;color:rgb(31,73,125);font-family:Arial,sans-serif">Mobile</span></b><span style="font-size:10pt;color:rgb(31,73,125);font-family:Arial,sans-serif">: <span style="white-space:pre-wrap"> </span><a value="+18582088105">858-208-8105</a></span></div>
<div style="margin:0in 0in 0.0001pt"><font color="#1f497d" face="Arial, sans-serif"><span style="font-size:13px"><b>Twitter:<span style="white-space:pre-wrap"> </span></b></span></font><a href="http://www.twitter.com/colinmcnamara" target="_blank">@colinmcnamara</a></div>
<div style="font-family:Calibri,sans-serif;font-size:11pt;margin:0in 0in 0.0001pt"><span style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px"><b>Linkedin</b>:<span style="white-space:pre-wrap"> </span></span><a href="http://www.linkedin.com/colinmcnamara" style="font-family:Arial,sans-serif;font-size:13px" target="_blank">www.</a><a href="http://www.linkedin.com/colinmcnamara" style="font-family:Arial,sans-serif;font-size:13px" target="_blank">linkedin.com/colinmcnamara</a></div>
<div style="font-family:Calibri,sans-serif;font-size:11pt;margin:0in 0in 0.0001pt"><b style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px">Blog</b><span style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px">:<span style="white-space:pre-wrap"> </span></span><a href="http://www.colinmcnamara.com/" style="font-family:Arial,sans-serif;font-size:13px" target="_blank">www.colinmcnamara.com</a></div>
<div style="font-family:Calibri,sans-serif;font-size:11pt;margin:0in 0in 0.0001pt"><b style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px">Email</b><span style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px">:</span><span style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px;white-space:pre-wrap"> </span><a>colin@2cups.com</a><span style="color:rgb(31,73,125);font-family:Arial,sans-serif;font-size:13px;white-space:pre-wrap"> </span></div>
<div style="font-family:Calibri,sans-serif;font-size:11pt;margin:0in 0in 0.0001pt"><br></div></div></div></div></div><br></div><br></div><br><br>
</div>
<br></div><div><div><div><div>On Oct 10, 2013, at 9:35 AM, Anne Gentle <<a>annegentle@justwriteclick.com</a>> wrote:</div><br><blockquote type="cite">
<div dir="ltr"><br><div><br><br><div>On Thu, Oct 10, 2013 at 11:06 AM, Colin McNamara <span dir="ltr"><<a></a></span></div></div></div></blockquote></div></div></div></div></div></div></blockquote></div><br><br clear="all">
<div><br></div></div><span><font color="#888888">-- <br>Anne Gentle<br><a>annegentle@justwriteclick.com</a>
</font></span></div></div><span><font color="#888888">
</font></span></blockquote><span><font color="#888888"><br><br>-- <br><div dir="ltr">Thank you!<div><br></div><div>Nermina Miller</div><div>Tech Writer and Editor</div></div><br>
</font></span></blockquote></div></div></div><span><font color="#888888"><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</font></span></div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Thank you!<div><br></div><div>Nermina Miller</div><div>Tech Writer and Editor</div></div>
</div>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Thank you!<div><br></div><div>Nermina Miller</div><div>Tech Writer and Editor</div></div>
</div></div></div></div></div>
</blockquote></div><br><br clear="all"><div><br></div></div></div><span><font color="#888888">-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</font></span></div>
<br></div></div><div>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></div></blockquote></div><span><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Lorin Hochstein<br><div>Lead Architect - Cloud Services</div><div>Nimbis Services, Inc.</div>
<div><a href="http://www.nimbisservices.com" target="_blank">www.nimbisservices.com</a></div>
</div>
</font></span></div>
</blockquote></div></div></div><span><font color="#888888"><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</font></span></div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div dir="ltr">Lorin Hochstein<br><div>Lead Architect - Cloud Services</div><div>Nimbis Services, Inc.</div><div><a href="http://www.nimbisservices.com" target="_blank">www.nimbisservices.com</a></div>
</div>
</div></div></div></div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>