<div dir="ltr">Hi Matt, sorry this dropped off my radar but this is a great discussion to have. More below.<div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Mar 10, 2014 at 9:47 PM, Matt Kassawara <span dir="ltr"><<a href="mailto:mkassawara@gmail.com" target="_blank">mkassawara@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">I'm wondering if the training guide maintainers could collaborate more with maintainers of other documents to reduce the amount of duplicate effort and increase parity. For example, the training guide labs could more easily reference newer releases of OpenStack and provide a smoother transition to the manual installation process by following the installation guide. Just throwing the idea out there...</div>
</blockquote><div><br></div><div><br></div><div><div style="font-family:arial,sans-serif;font-size:13px">Sean and Colin, you have been the leaders for the community training efforts, and I'd like to get your input. <br>
</div><div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">We have been incubating the training guides in the Documentation Program. It would be great to walk through some of the ways the training group could graduate, and one of the questions we keep having is about scope and strategically leveraging docs efforts. What's your sense of these scope questions related to where the training manuals are currently?</div>
<div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px"><pre style="white-space:pre-wrap;margin-bottom:0px;margin-top:0px;padding:0px"><code>** Project must have a clear and defined scope.</code></pre>
<pre style="white-space:pre-wrap;margin-bottom:0px;margin-top:0px;padding:0px"><code>** Project's scope should represent a measured progression for OpenStack as a
whole.
** Project should not inadvertently duplicate functionality present in other
OpenStack projects. If they do, they should have a clear plan and timeframe
to prevent long-term scope duplication.</code></pre><pre style="white-space:pre-wrap;margin-bottom:0px;margin-top:0px;padding:0px"><code>** Project should leverage existing functionality in other OpenStack projects
as much as possible</code></pre><br>Duplication and correct/strategic leverage is a concern for me - reviewing updates to the training manuals when the information is also duplicated elsewhere makes for double the work for the docs core reviewers. Examples:</div>
<div style="font-family:arial,sans-serif;font-size:13px">- Vagrant or VM install instructions rather than leveraging and improving the community install guide or ensuring DevStack is working well (and DevStack is not in the scope of personas for openstack-manuals).</div>
<div style="font-family:arial,sans-serif;font-size:13px">- How to contribute to OpenStack docs maintained in the openstack-manuals repo itself, rather than one-source-of-truth in the wiki</div><div style="font-family:arial,sans-serif;font-size:13px">
- Apparent imports of documentation from other places, such as <a href="http://docs.openstack.org/developer/nova/devref/rpc.html" target="_blank">http://docs.openstack.org/developer/nova/devref/rpc.html</a> going into <a href="https://review.openstack.org/#/c/80486/5/doc/training-guides/module001-ch008-queues-messaging.xml" target="_blank">https://review.openstack.org/#/c/80486/5/doc/training-guides/module001-ch008-queues-messaging.xml</a> -- this is problematic because it wasn't written based on the Conventions in the first place, and may or may not be something we should clean up and put into the Cloud Admin Guide. By having the training manuals take that but not improve it or find a better integration point, we have added to technical debt rather than improving the docs. Another recent example is <a href="https://review.openstack.org/#/c/80503/3" target="_blank">https://review.openstack.org/#/c/80503/3</a> where Shilla spent time on a patch before realizing that the file wasn't being used anywhere, and Andreas spent time reviewing before realizing it wasn't being used. </div>
<div style="font-family:arial,sans-serif;font-size:13px">- We still have an audience concern, with the developer training manual not matching any persona in the openstack-manuals repo.</div><div style="font-family:arial,sans-serif;font-size:13px">
- When the training-guides folder gets updated and pushed, not waiting for +2 from two cores, this caused problems in the past. I think they're resolved now, but I would prefer that the training team can eventually have their own core team, reviewers, and repository. How close are we to meeting that goal of graduation and a separate, diverse team?<br>
</div><div style="font-family:arial,sans-serif;font-size:13px"><br></div><div style="font-family:arial,sans-serif;font-size:13px">I'd love to start the conversation here but let's also plan to continue it in team meetings and at the summit.</div>
</div><div style="font-family:arial,sans-serif;font-size:13px">
<br></div><div style="font-family:arial,sans-serif;font-size:13px">Thanks,</div><div style="font-family:arial,sans-serif;font-size:13px">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">
<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></div></div>