<div dir="ltr"><div>I just ran through an install last week and found 3 issues. One was a bad link which I put a patch up for, the other there was a Horizon bug for, and the last was Placement and I've reached out in #openstack-placement but need to follow up I'm willing to patch the docs but not sure where as there's 2 options. I only did Keystone, Nova, Glance, Neutron, Placement, and Cinder so not sure the state of any others</div><div><br></div><div>Thanks,</div><div><br></div><div>Amy (spotz)<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Jun 4, 2020 at 9:11 AM Jeremy Stanley <<a href="mailto:fungi@yuggoth.org">fungi@yuggoth.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 2020-06-04 18:40:45 +0900 (+0900), Akihiro Motoki wrote:<br>
> During the doc migration, the installation guide was moved to<br>
> individual project repos.<br>
> I see problems in installation guide maintenance after the migration.<br>
> <br>
> - The installation guide is not maintained well perhaps in many projects.<br>
>   AFAIK they are not verified well at least in horizon and neutron.<br>
> - Even if we try to verify it, it is a tough thing because we need to<br>
> prepare base distribution<br>
>   and setup other projects together (of course it depends on projects).<br>
>   This leads to a development bandwidth and priority issue.<br>
> - We sometimes receive bug reports on the installation guide, but it<br>
> is not easy for the<br>
>   upstream team confirm them and verify fixes.<br>
> <br>
> I guess the installation guides are not being maintained well from<br>
> these reasons.<br>
> Any thoughts on this situation? (This is my first question.)<br>
[...]<br>
<br>
This could be an ambitious proposal, but the way the Zuul community<br>
has approached the problem is that it has a CI job which mirrors its<br>
"quick start" deployment guide, with a review policy and embedded<br>
comments indicating that any time one is changed the other must also<br>
be changed to match. In essence, run automatic tests of the exact<br>
same steps you're documenting, or as many of them as you possibly<br>
can at least, and keep the two in sync.<br>
<br>
Since its inception, OpenStack has been distinguished by how its<br>
approach to automated testing is superior to the obsolete practice<br>
of a human sitting in front of a computer manually trying the same<br>
sets of documented steps over and over... which is exactly how the<br>
installation guides were still being tested (or more to the point,<br>
why they've not been tested with any real consistency for years).<br>
-- <br>
Jeremy Stanley<br>
</blockquote></div>