<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Oct 10, 2013 at 12:02 PM, Colin McNamara <span dir="ltr"><<a href="mailto:colin@2cups.com" target="_blank">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">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 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">
<div><div><div class="im"><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 class="MsoNormal" style="font-size:medium;font-family:Helvetica;font-weight:normal">Regards,</p><p class="MsoNormal" 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 href="tel:858-208-8105" value="+18582088105" target="_blank">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 href="mailto://colin@2cups.com" target="_blank">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 class="h5"><div><div>On Oct 10, 2013, at 9:35 AM, Anne Gentle <<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>> wrote:</div><br><blockquote type="cite">
<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Oct 10, 2013 at 11:06 AM, Colin McNamara <span dir="ltr"><<a href="mailto:colin@2cups.com" target="_blank">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">Tom (And list). What we have been finding is that the Dev Docs are a rich source for conceptual discussions of components to be installed. A specific example is the messaging service used in Nova. In the Associate guide, there is an installation task of installing and configuring RabbitMQ. Directly before that configuration task there is a conceptual task of understanding (at a high level) the messaging architecture, and the components that enable its operation. <div>
<br></div><div>The RPC section of the Nova developer documentation (found here - <a href="http://docs.openstack.org/developer/nova/devref/rpc.html" target="_blank">http://docs.openstack.org/developer/nova/devref/rpc.html</a>) has a very detailed deep dive into this topic. I believe the first section "AMQP and Nova" is appropriate to integrate as the conceptual item for this installation task. In more advanced courses, subsequent sections such as "Broker Load" and "RabbitMQ Gotchas" will be appropriate to include. </div>
</div></blockquote><div><br></div><div>These sound like the types of info that both Python devs and deployers/admins/architects would benefit from. Thierry has often noted this difficulty, how to share that info with both audiences. Here's what we've done based on the participation and maintenance data we see.</div>
<div><br></div><div>For the Filter conceptual info, we brought it directly into openstack-manuals, and maintain it there. I think the same could happen with AMQP. Realize the AMQP page you reference is over a year old. The Filter page in nova was updated 2 months ago. The one in openstack-manuals was updated 10 days ago. </div>
<div><br></div><div>I think you need to put the info where it'll be updated more often, and time and time again, that's in openstack-manuals.</div><div><br></div><div>I had hoped that was your role here, to identify what's missing in the manuals and add it. I think you're identifying it, all we're asking is that you bring it in where needed, not in an automated way, but in a maintainable trackable way. </div>
<div><br></div><div>Or, do a proof of concept where specific conceptual content builds on Jenkins and integrates with the openstack-manuals. Or, wait for Todd Morey's proof of concept with mixed-type content. </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 style="word-wrap:break-word"><div><br></div><div>
I'd like to also address the subject of improving manuals content within training-manuals by copying vs including external sources. Improving the training-manuals content is an important goal. I however have been a bit of a stickler within Training-Guides on content duplication. I personally don't believe that it is sustainable to maintain two completely separate sources of documentation in a six month release cycle with major changes in structure each release while maintaining forward progress on the advanced courses. I however may be completely off base on this belief and welcome comments and external perspective. </div>
<div><br></div><div>With that being said, in a perfect wold the Developer Docs would all be in XML that could be included into openstack-manuals content natively. The world we live in has developer content written in ReStructured Text, which is extremely easy for people to update and I doubt will change (or should be changed). The next best thing for me would be for Jenkins to create docbooks XML content on build, or a similar XML content that could be easily included at a granular level into the larger documentation base. </div>
</div></blockquote><div><br></div><div>Conceptual information is welcomed in openstack-manuals, and like I note above, the pattern we see is that the dev docs are not well-maintained. My vision is that docbook becomes more invisible but we need tooling for that.</div>
<div>Thanks Colin and Sean for bringing up what you find as you go!</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 style="word-wrap:break-word">
<div><br></div><div><br></div><div>Regards,</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 class="MsoNormal" style="font-size:medium;font-family:Helvetica;font-weight:normal">Colin</p><span><font color="#888888"><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 href="tel:858-208-8105" value="+18582088105" target="_blank">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 href="mailto://colin@2cups.com" target="_blank">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></font></span></div></div></div><br></div><br></div><br><br>
</div><div><div>
<br><div><div>On Oct 9, 2013, at 9:02 PM, Tom Fifield <<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>> wrote:</div><br><blockquote type="cite">Oh?<br><br>Can you point out some of the good sections for associates in the devref you're looking at? We should also work on improving the manuals for you if there's stuff missing. In theory the devref is only for dev stuff, which is why I was asking - I didn't think you were up to writing the developer training yet :D<br>
<br>Regards,<br><br><br>Tom<br><br>On 10/10/13 15:00, Sean Roberts wrote:<br><blockquote type="cite">Good question. The immediate need is for the associate guide that we are<br>working on right now.<br><br><br>Sean Roberts<br>
Infrastructure Strategy<br><a href="mailto:seanrob@yahoo-inc.com" target="_blank">seanrob@yahoo-inc.com</a> <<a href="mailto:seanrob@yahoo-inc.com" target="_blank">mailto:seanrob@yahoo-inc.com</a>> <a href="tel:%28925%29%20980-4729" value="+19259804729" target="_blank">(925) 980-4729</a><br>
<br>On Oct 9, 2013, at 7:54 PM, Tom Fifield <<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a><br><<a href="mailto:tom@openstack.org" target="_blank">mailto:tom@openstack.org</a>>><br> wrote:<br>
<br><blockquote type="cite">Hi Sean,<br><br>Just wondering - is this mainly for the "Developer Training Guide" ?<br><br>Regards,<br><br><br>Tom<br><br>On 10/10/13 11:48, Sean Roberts wrote:<br><blockquote type="cite">
Sounds great. I'll post my latest code to my repo and share.<br><br>~sean<br><br><blockquote type="cite">On Oct 9, 2013, at 17:00, "David Cramer" <<a href="mailto:david.cramer@rackspace.com" target="_blank">david.cramer@rackspace.com</a><br>
<<a href="mailto:david.cramer@rackspace.com" target="_blank">mailto:david.cramer@rackspace.com</a>>> wrote:<br><br>Hi Sean,<br>xslt would be well-suited to cleaning up the output of pandoc and<br>converting it to DocBook 5.x. This could be invoked from your python<br>
script:<br><br><a href="https://svn.code.sf.net/p/docbook/code/trunk/docbook/relaxng/tools/db4-upgrade.xsl" target="_blank">https://svn.code.sf.net/p/docbook/code/trunk/docbook/relaxng/tools/db4-upgrade.xsl</a><br><br>If you have other cleanup to perform, we could add the necessary logic<br>
to the db4-upgrade.xsl.<br><br>I'll be happy to help with the xslt and I think the result would be more<br>robust.<br><br>Regards,<br>David<br><br><blockquote type="cite">On 10/09/2013 06:37 PM, Sean Roberts wrote:<br>
The training-manuals team is proposing a blueprint to implement rst to<br>xml conversion script. This code is used to convert devref project rst<br>documentation into xml that the openstack manuals project can use. The<br>
Training-manuals sub-project will use xi:include statements so the<br>converted xml becomes part of the training guides during build. The<br>conversion script will live in the ./training-guide/sources sub<br>directory of the training-manuals sub-project. The converted xml gets<br>
placed within ./training-guide/sources/<project> directories. The<br>conversion script will be run at the same time as when the<br>openstack-manuals repo updates are pulled. This will allow the training<br>manuals team to find xml content and include it with the training<br>
guides. If the source RST has a bug, then the RST source will be<br>patched, and the XML will get the bug fix through the next run of the<br>conversion script.<br><br>Blueprint<br>here<br><a href="https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion</a><br>
Wiki details<br>here<br><a href="https://wiki.openstack.org/wiki/Training-manuals#RST-XML_Conversion_automation" target="_blank">https://wiki.openstack.org/wiki/Training-manuals#RST-XML_Conversion_automation</a><br><br>Sean Roberts<br>
Infrastructure Strategy<br><a href="mailto:seanrob@yahoo-inc.com" target="_blank">seanrob@yahoo-inc.com</a> <mailto:<a href="mailto:seanrob@yahoo-inc.com" target="_blank">seanrob@yahoo-inc.com</a>> <a href="tel:%28925%29%20980-4729" value="+19259804729" target="_blank">(925) 980-4729</a><br>
<br><br><br>_______________________________________________<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>
</blockquote><br></blockquote><br>_______________________________________________<br>Openstack-docs mailing list<br><a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a><br>
<mailto:<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></blockquote><br><br>_______________________________________________<br>Openstack-docs mailing list<br><a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.openstack.org</a><br><mailto:<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></blockquote><br></blockquote><br><br>_______________________________________________<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>
</blockquote></div><br></div></div></div></div><br>_______________________________________________<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></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>
</blockquote></div><br></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>