<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Title" content="">
<meta name="Keywords" content="">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-reply;
font-family:Calibri;
color:windowtext;}
span.msoIns
{mso-style-type:export-only;
mso-style-name:"";
text-decoration:underline;
color:teal;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body bgcolor="white" lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">Hi team leads,</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">I’m sure some of you may or may not have seen, I am currently pushing for a ‘documentation review period’ to be officially integrated to the project release schedule. You can see the draft verison for pike here:
<a href="https://releases.openstack.org/pike/schedule.html" target="_blank">https://releases.openstack.org/pike/schedule.html</a> If anyone has not seen my email, you can view here:
<a href="http://lists.openstack.org/pipermail/openstack-dev/2017-March/113144.html" target="_blank">
http://lists.openstack.org/pipermail/openstack-dev/2017-March/113144.html</a> So far, we have mostly positive responses.</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">My reason for bringing this up is because we have unfortunately swept up with a lot of bugs post-Ocata release referencing out-of-date content in our guides. Several guides are still referencing Newton content, or were never updated
and are unworkable. These guides include our Installation manuals and reference guides.</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">From what I can tell, this is a by-product of miscommunication. But I would like to improve on this, and ensure it does not happen again in the future. Here is a link the overview of our release tasks currently:
<a href="https://docs.openstack.org/contributor-guide/release/taskoverview.html" target="_blank">
https://docs.openstack.org/contributor-guide/release/taskoverview.html</a> </span>
<o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">I propose we renew what the specialty leads are doing on our side at release time (especially with the guides that are on the release schedule), and what the cross-project liaisons (CPLs) for docs need to be doing on their side
as there appears to be a little bit of discord between the two currently.</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<b><span style="font-size:11.0pt">Brian and Maria</span></b><span style="font-size:11.0pt"> – as our most recent release managers, how did pinging the CPLs go before release? Were they responsive?</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<div>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:0in;margin-right:0in;margin-bottom:12.0pt;margin-left:.5in">
I'm not sure about the status of the other guides, but certainly the Install Guide has proved problematic. I think we should explicitly ask the CPLs from the projects included in the Install Guide to review their chapters. If that had happened we wouldn't have
missed the Cellsv2 and Placement content. To be honest, we should have known about those two items prior to the release process starting. Perhaps we need to ask CPLs early in the cycle to send us a list of items they have planned for the next release that
they think will require changes to our documentation. We might get some false positives with work that doesn't make it into the release or that doesn't actually belong in our books, but I think that is better than scrambling around after the release trying
to fix broken docs.<o:p></o:p></p>
<p class="MsoNormal" style="margin-bottom:12.0pt"><br>
Context for those who are unaware: <a href="https://bugs.launchpad.net/openstack-manuals/+bug/1663485">
https://bugs.launchpad.net/openstack-manuals/+bug/1663485</a> We have escalated one of our install-guide bugs to CRITICAL this morning after Brian is yet to break through with the nova instructions. At the moment it’s looking pretty good, but we’ve got the
nova team looking at it.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:0in;margin-right:0in;margin-bottom:12.0pt;margin-left:.5in">
So maybe a two-pronged approach?<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">1. Connect with CPLs early in the cycle to find out what they have in the pipeline that we should keep an eye on. As we get close to release we can check on those items to see where things are at.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:0in;margin-right:0in;margin-bottom:12.0pt;margin-left:.5in">
2. Make the review process easier for CPLs by sending them a list of chapters/sections they should review prior to release. Perhaps tracked on an etherpad so they can record issues and we can track progress.<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in">Brian<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">This looks very similar to what I had in mind, that’s great :) I like where you’re headed. The way we are currently doing is simply not working. I have found that many are willing, but that doesn’t mean it’s actually getting done. Potentially
– as you said – holding them accountable earlier in the release might save us from any further problems.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Provided nobody disagreed with this style of approach, we integrate it into our Contributor Guide section for release management. At the moment, we have 2 lines that indicate it’s important – but we should integrate some steps.
<a href="https://docs.openstack.org/contributor-guide/release/taskdetail.html">https://docs.openstack.org/contributor-guide/release/taskdetail.html</a>
<o:p></o:p></p>
</div>
<div>
<p class="MsoNormal" style="margin-left:.5in"> <o:p></o:p></p>
</div>
<blockquote style="border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in">
<div>
<div>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">Team – I want your genuine opinions and suggestions on how we can best improve this process outside of making it official. Do we need to have liaisons that are better integrated in the documentation team? Perhaps a partnership
with a doc person?</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">As much as I appreciate the argument that, “If $project don’t update their docs, it’s their problem.” It all comes down to the user, and if the user cannot install $project because it’s not updated, then what do we have?</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">Looking forward to your thoughts and opinions,</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt">Alex</span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
<p class="MsoNormal" style="mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;margin-left:.5in">
<span style="font-size:11.0pt"> </span><o:p></o:p></p>
</div>
</div>
<p class="MsoNormal" style="mso-margin-top-alt:0in;margin-right:0in;margin-bottom:12.0pt;margin-left:.5in">
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">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><o:p></o:p></p>
</blockquote>
<p class="MsoNormal" style="margin-left:.5in"><o:p> </o:p></p>
</div>
</body>
</html>