On 2020-06-04 18:40:45 +0900 (+0900), Akihiro Motoki wrote:

During the doc migration, the installation guide was moved to individual project repos. I see problems in installation guide maintenance after the migration.

- The installation guide is not maintained well perhaps in many projects. AFAIK they are not verified well at least in horizon and neutron. - Even if we try to verify it, it is a tough thing because we need to prepare base distribution and setup other projects together (of course it depends on projects). This leads to a development bandwidth and priority issue. - We sometimes receive bug reports on the installation guide, but it is not easy for the upstream team confirm them and verify fixes.

I guess the installation guides are not being maintained well from these reasons. Any thoughts on this situation? (This is my first question.) [...]

This could be an ambitious proposal, but the way the Zuul community has approached the problem is that it has a CI job which mirrors its "quick start" deployment guide, with a review policy and embedded comments indicating that any time one is changed the other must also be changed to match. In essence, run automatic tests of the exact same steps you're documenting, or as many of them as you possibly can at least, and keep the two in sync. Since its inception, OpenStack has been distinguished by how its approach to automated testing is superior to the obsolete practice of a human sitting in front of a computer manually trying the same sets of documented steps over and over... which is exactly how the installation guides were still being tested (or more to the point, why they've not been tested with any real consistency for years). -- Jeremy Stanley

On 6/4/20 11:40 AM, Akihiro Motoki wrote:

- Drop the installation guide (per OS or as a whole)

Please don't do that.

Most users deploy OpenStack using deployment projects (or their own deployment tools).

Then how would the person writing the deployment tool do the work?

Step-by-step guides might be useful from educational perspective

They are.

but unmaintained guides are not useful.

What I would very much prefer would be a more general guide on how to setup a MySQL db for a project, and how to setup an endpoint. Then the individual project documentation would just point at that doc, and inform the reader what is the default for: - service name - port number - endpoint URL Then we need a more general descriptions of what services are for, and where to deploy then. For example, in Neutron, it'd be enough to explain that: - neutron-rpc-server should be deployed on 3 controllers - neutron-api should go on 3 controllers, with HAproxy in front - dhcp-agent can be deployed anywhere, but then l3 & l2 agent must be on the same server as well - metadata-agent, ovs-agent and l3-agent must be on each compute This type of explanation is a way more useful than a step-by-step: apt-get install neutron-l3-agent where we're giving zero explanation of what the l3 agent does, where it should be installed, and why.

From the Debian perspective, I would have like to have a specific place where we could have explained how the Debconf system works, and how it has been designed in the package (ie: in a way so that a full cluster deployment could be done only with preseed, but also in a way so that it doesn't bother anyone using a deployment tool like Puppet or Ansible). Currently, there's no place where to write about this. Though it was documented, and well documented, at the time.

I believe the install-guide for Debian was kind of nearly perfect around in 2016, with these specific chapters, and lots of debconf screenshots to explain it all. That is just *GONE*. This is frustrating, and a disservice for our users. More generally, I found the move of the install guide to each individual project was a huge regression, and since then, it has a lot less value. All the work I did at the time to document things for Debian has been slowly removed. I have absolutely no idea why contributors have been doing that, and I don't think that's fair to have done it. I also found that the conditionals we had at the time (ie: if osname=Ubuntu or Debian, that kind of things...) was very helpful. These days, we're duplicating, that's really silly. Back at the time, the decision was made because some core contributors to the install guide just left the project. It was at the time said that moving the maintenance to each individual projects would scale nicer. I am now convince that this is the exact opposite that has happened: docs are maintained a lot less now, with lower quality, and less uniformity. So I am convince that we did a very bad move at the time, one that we shouldn't have made. If we were going back to what we would do in 2016, I would contribute again. But considering what the install guide has become, this really isn't motivating. Your thoughts? Cheers, Thomas Goirand (zigo)

On Thu, 2020-06-04 at 18:40 +0900, Akihiro Motoki wrote:

Hi,

During the doc migration, the installation guide was moved to individual project repos. I see problems in installation guide maintenance after the migration.

- The installation guide is not maintained well perhaps in many projects. AFAIK they are not verified well at least in horizon and neutron. - Even if we try to verify it, it is a tough thing because we need to prepare base distribution and setup other projects together (of course it depends on projects). This leads to a development bandwidth and priority issue. - We sometimes receive bug reports on the installation guide, but it is not easy for the upstream team confirm them and verify fixes.

I guess the installation guides are not being maintained well from these reasons. Any thoughts on this situation? (This is my first question.)

As has been summarized above and elsewhere, this is almost certainly a bandwidth and priority issue.

If a project team has no bandwidth to maintain it, what is a recommended way? I see several options: - Drop the installation guide (per OS or as a whole) -- If drop what should the criteria be? - Keep the installation guide with warnings like "the upstream team does not maintain it and just host it". - Keep it as-is (unmaintained)

Personally, I'd love to see per-cycle hackathons where people sit down and install an OpenStack deployment manually on each OS, however, I can't see that happening and most teams have no interest in setting aside time each cycle to validate this themselves. The latter point is unfortunate, since the process of doing such manual work often serves to highlight the uglier corners of project configuration, but it is also understandable since this work is often tedious and unrewarding. As you've mentioned below, most (all?) people using OpenStack for anything more than a learning tool are installing using a deployment tool. I personally suspect the amount of people using OpenStack on CentOS/RHEL without TripleO/Director or something like Kolla is exceedingly low, bordering on non-existent. Similarly, I would assume the Ubuntu users are using a combo of MAAS/Juju while the amount of people installing OpenStack on SUSE with anyting is likely approaching zero now, given their divestment. All in all, while I'd rather we didn't have to do so, I think deleting the installation guides is probably the right move. It sucks and will result in a worse experience for our users, but it's just a reflection of reality. Thanks for bringing this up, Stephen

Finally, I am not sure we need to maintain step-by-step guides on installations and I wonder we need to drop them at some time. Most users deploy OpenStack using deployment projects (or their own deployment tools). Step-by-step guides might be useful from educational perspective but unmaintained guides are not useful.

Thanks in advance,

-- Akihiro Motoki (amotoki)