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)