<div dir="ltr">I really believe that this idea will makes us work harder on keeping our docs in place and will make it for a better documented producted by release date. <div>As shared before, I do believe that this is isn't easy and will demand a lot of effort from some teams, specially smaller teams with too much to do, but we from Sahara are on board with this approach and will try our best to do so.</div><div><br></div><div>Thanks,</div></div><br><div class="gmail_quote"><div dir="ltr">On Thu, Mar 2, 2017 at 7:33 AM Alexandra Settle <<a href="mailto:a.settle@outlook.com">a.settle@outlook.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg">
<div class="m_-6225317059137706720WordSection1 gmail_msg">
<p class="MsoNormal gmail_msg"><span style="font-size:11.0pt;font-family:Calibri" class="gmail_msg"><u class="gmail_msg"></u> <u class="gmail_msg"></u></span></p>
<p class="MsoNormal gmail_msg"><span style="font-size:11.0pt;font-family:Calibri" class="gmail_msg"><u class="gmail_msg"></u> <u class="gmail_msg"></u></span></p>
<div style="border:none;border-top:solid #b5c4df 1.0pt;padding:3.0pt 0in 0in 0in" class="gmail_msg">
<p class="MsoNormal gmail_msg" style="margin-left:.5in"><b class="gmail_msg"><span style="font-family:Calibri;color:black" class="gmail_msg">From:
</span></b><span style="font-family:Calibri;color:black" class="gmail_msg">John Dickinson <<a href="mailto:me@not.mn" class="gmail_msg" target="_blank">me@not.mn</a>><br class="gmail_msg">
<b class="gmail_msg">Reply-To: </b>"OpenStack Development Mailing List (not for usage questions)" <<a href="mailto:openstack-dev@lists.openstack.org" class="gmail_msg" target="_blank">openstack-dev@lists.openstack.org</a>><br class="gmail_msg">
<b class="gmail_msg">Date: </b>Wednesday, March 1, 2017 at 11:50 PM<br class="gmail_msg">
<b class="gmail_msg">To: </b>OpenStack Development Mailing List <<a href="mailto:openstack-dev@lists.openstack.org" class="gmail_msg" target="_blank">openstack-dev@lists.openstack.org</a>><br class="gmail_msg">
<b class="gmail_msg">Cc: </b>"<a href="mailto:openstack-docs@lists.openstack.org" class="gmail_msg" target="_blank">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org" class="gmail_msg" target="_blank">openstack-docs@lists.openstack.org</a>><br class="gmail_msg">
<b class="gmail_msg">Subject: </b>Re: [openstack-dev] [docs][release][ptl] Adding docs to the release schedule<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</div>
<div class="gmail_msg">
<p class="MsoNormal gmail_msg" style="margin-left:.5in"><u class="gmail_msg"></u> <u class="gmail_msg"></u></p>
</div>
<div class="gmail_msg"></div></div></div><div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg"><div class="m_-6225317059137706720WordSection1 gmail_msg"><div class="gmail_msg">
<div class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">On 1 Mar 2017, at 10:07, Alexandra Settle wrote:<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</div>
<div class="gmail_msg">
<blockquote style="border:none;border-left:solid #777777 1.5pt;padding:0in 0in 0in 4.0pt;margin-left:0in;margin-right:0in;margin-bottom:3.75pt" class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica;color:#777777" class="gmail_msg">On 3/1/17, 5:58 PM, "John Dickinson" <<a href="mailto:me@not.mn" class="gmail_msg" target="_blank">me@not.mn</a>> wrote:<br class="gmail_msg">
<br class="gmail_msg">
<br class="gmail_msg">
<br class="gmail_msg">
On 1 Mar 2017, at 9:52, Alexandra Settle wrote:<br class="gmail_msg">
<br class="gmail_msg">
> Hi everyone,<br class="gmail_msg">
><br class="gmail_msg">
> I would like to propose that we introduce a “Review documentation” period on the release schedule.<br class="gmail_msg">
><br class="gmail_msg">
> We would formulate it as a deadline, so that it fits in the schedule and making it coincide with the RC1 deadline.<br class="gmail_msg">
><br class="gmail_msg">
> For projects that are not following the milestones, we would translate this new inclusion literally, so if you would like your project to be documented at docs.o.o, then doc must be introduced and reviewed one month before the branch is cut.<br class="gmail_msg">
<br class="gmail_msg">
Which docs are these? There are several different sets of docs that are hosted on docs.o.o that are managed within a project repo. Are you saying those won't get pushed to<br class="gmail_msg">
docs.o.o if they are patched within a month of the cycle release?<br class="gmail_msg">
<br class="gmail_msg">
The only sets of docs that are published on the docs.o.o site that are managed in project-specific repos is the project-specific installation guides. That management is entirely up to the team themselves, but I would like to push for the integration of a “documentation
review” period to ensure that those teams are reviewing their docs in their own tree.<br class="gmail_msg">
<br class="gmail_msg">
This is a preferential suggestion, not a demand. I cannot make you review your documentation at any given period.<br class="gmail_msg">
<br class="gmail_msg">
The ‘month before’ that I refer to would be for introduction of documentation and a review period. I will not stop any documentation being pushed to the repo unless, of course, it is untested and breaks the installation process.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</blockquote>
</div>
<div class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">There's the dev docs, the install guide, and the api reference. Each of these are published at docs.o.o, and each have elements that need to be up-to-date with a release.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</div>
<div class="gmail_msg">
<blockquote style="border:none;border-left:solid #777777 1.5pt;padding:0in 0in 0in 4.0pt;margin-left:0in;margin-right:0in;margin-bottom:3.75pt" class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica;color:#777777" class="gmail_msg">><br class="gmail_msg">
> In the last week since we released Ocata, it has become increasingly apparent that the documentation was not updated from the development side. We were not aware of a lot of new enhancements, features, or major bug fixes for certain projects. This means we
have released with incorrect/out-of-date documentation. This is not only an unfortunately bad reflection on our team, but on the project teams themselves.<br class="gmail_msg">
><br class="gmail_msg">
> The new inclusion to the schedule may seem unnecessary, but a lot of people rely on this and the PTL drives milestones from this schedule.<br class="gmail_msg">
><br class="gmail_msg">
> From our side, I endeavor to ensure our release managers are working harder to ping and remind doc liaisons and PTLs to ensure the documentation is appropriately updated and working to ensure this does not happen in the future.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</blockquote>
</div>
</div></div></div><div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg"><div class="m_-6225317059137706720WordSection1 gmail_msg"><div class="gmail_msg"><div class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">Overall, I really like the general concept here. It's very important to have good docs. Good docs start with the patch, and we should be encouraging the idea of "patch must have both tests and
docs before landing".<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</div></div></div></div><div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg"><div class="m_-6225317059137706720WordSection1 gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><p class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">I’m glad to hear you think so :) this is entirely my thought process.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p></div></div></div></div><div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg"><div class="m_-6225317059137706720WordSection1 gmail_msg"><div class="gmail_msg"><div class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">On a personal note, though, I think I'll find this pretty tough. First, it's really hard for me to define when docs are "done", so it's hard to know that the docs are "right" at the time of release.
Second, docs are built and published at each commit, so updating the docs "later, in a follow-on patch" is a simple thing to hope for and gives fast feedback, even after a release. (Of course the challenge is actually
<em class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">doing</span></em> the patch later--see my previous paragraph.)<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</div></div></div></div><div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg"><div class="m_-6225317059137706720WordSection1 gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><p class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">So, unfortunately, I can give you no promise this was ever intended to be an easy inclusion. But in fairness, this is something teams should have already been doing.
<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
<p class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">However, as a PTL – you already have enough on your plate. We recommend a docs liaison that is not the PTL so that the individual is able to dedicate time to reviewing the documentation to the best of their ability. The
docs being “done” = all new features that have a user impact are documented, and “right” = the user is able to install $project without major incident.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
<p class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">However, to reiterate my point before – we cannot force any team to do anything, but we would like to start actively encouraging the project teams to start seeing documentation as an important part of the release process,
just as they would anything else.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
<p class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">“Treat docs like code” means so much more than just having a contribution process that is the same, it means treating the documentation with the same importance you would your code.<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
<p class="gmail_msg"><span style="font-family:Helvetica" class="gmail_msg">It all comes down to the user, and if the user cannot install the $project, then what do we have?<u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</div></div></div></div><div bgcolor="white" lang="EN-US" link="blue" vlink="purple" class="gmail_msg"><div class="m_-6225317059137706720WordSection1 gmail_msg"><div class="gmail_msg">
<div class="gmail_msg">
<blockquote style="border:none;border-left:solid #777777 1.5pt;padding:0in 0in 0in 4.0pt;margin-left:0in;margin-right:0in;margin-bottom:3.75pt" class="gmail_msg">
<p style="margin-left:.5in" class="gmail_msg"><span style="font-family:Helvetica;color:#777777" class="gmail_msg">><br class="gmail_msg">
> Thanks,<br class="gmail_msg">
><br class="gmail_msg">
> Alex<br class="gmail_msg">
<br class="gmail_msg">
<br class="gmail_msg">
> __________________________________________________________________________<br class="gmail_msg">
> OpenStack Development Mailing List (not for usage questions)<br class="gmail_msg">
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" class="gmail_msg" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br class="gmail_msg">
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" class="gmail_msg" target="_blank"><span style="color:#777777" class="gmail_msg">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</span></a><br class="gmail_msg">
<br class="gmail_msg">
<br class="gmail_msg">
__________________________________________________________________________<br class="gmail_msg">
OpenStack Development Mailing List (not for usage questions)<br class="gmail_msg">
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" class="gmail_msg" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br class="gmail_msg">
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" class="gmail_msg" target="_blank"><span style="color:#777777" class="gmail_msg">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</span></a><u class="gmail_msg"></u><u class="gmail_msg"></u></span></p>
</blockquote>
</div>
</div></div></div>
__________________________________________________________________________<br class="gmail_msg">
OpenStack Development Mailing List (not for usage questions)<br class="gmail_msg">
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" class="gmail_msg" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br class="gmail_msg">
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" class="gmail_msg" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br class="gmail_msg">
</blockquote></div>