Open Stack

On Mon, 24 May 2021 at 09:30, Mark Goddard <mark at stackhpc.com> wrote:
>
> On Fri, 14 May 2021 at 21:27, Klemen Pogacnik <klemen at psi-net.si> wrote:
> >
> > Hello!
>
> Hi Klemen,
>
> Thank you for your evaluation of the documentation. I think a lot of
> it aligns with the discussions we had in the Kolla Kalls [1] some time
> ago. I'll add notes inline.
>
> It's worth looking at other similar projects for inspiration, e.g. OSA
> [2] and TripleO [3].
>
> [1] https://etherpad.opendev.org/p/kollakall
> [2] https://docs.openstack.org/openstack-ansible/latest/
> [3] https://docs.openstack.org/tripleo-docs/latest/
>
> Mark
>
> >
> > I promised to prepare my view as a user of kolla-ansible on its documentation. In my opinion the division between admin guides and user guides is artificial, as the user of kolla-ansible is actually the cloud administrator.
>
> Absolutely agreed.
>
> >
> > Maybe it would be good to think about reorganizing the structure of documentation. Many good chapters are already written, they only have to be positioned in the right place to be found more easily.
>
> Agreed also. We now have redirect support [4] in place to keep old
> links working, assuming only whole pages are moved.
>
> [4] doc/source/_extra/.htaccess
>
> >
> > So here is my proposal of kolla-ansible doc's structure:
> >
> > 1. Introduction
> > 1.1. mission
> > 1.2. benefits
> > 1.3. support matrix
>
> How about a 'getting started' page, similar to [5]?
>
> [5] https://docs.openstack.org/kayobe/latest/getting-started.html
>
> > 2. Architecture
> > 2.1. basic architecture
> > 2.2. HA architecture
> > 2.3. network architecture
> > 2.4. storage architecture
> > 3. Workflows
> > 3.1. preparing the surroundings (networking, docker registry, ...)
> > 3.2. preparing servers (packages installation)
>
> Installation of kolla-ansible should go here.
>
> > 3.3. configuration (of kolla-ansible and description of basic logic for configuration of Openstack modules)
> > 3.4. 1st day procedures (bootstrap, deploy, destroy)
> > 3.5. 2nd day procedures (reconfigure, upgrade, add, remove nodes ...)
> > 3.6. multiple regions
> > 3.7. multiple cloud
> > 3.8. security
> > 3.9. troubleshooting (how to check, if cloud works, what to do, if it doesn't)
>
> > 4. Use Cases
> > 4.1. all-in-one
> > 4.2. basic vm multinode
> > 4.3. some production use cases
>
> What do these pages contain? Something like the current quickstart?
>
> > 5. Reference guide
> > Mostly the same structure as already is. Except it would be desirable that description of each module has:
> > - purpose of the module
> > - configuration of the module
> > - how to use it with links to module docs
> > - basic troubleshooting
> > 6. Contributor guide
> >
> >
> > The documentation also needs figures, pictures, diagrams to be more understandable.  So at least in the first chapters some of them shall be added.
>
> This is a common request from users. We have lots of reference
> documentation, but need more high level architectural information and
> diagrams. Unfortunately this type of documentation is quite hard to
> create, but we would welcome improvements.
>
> >
> >
> > I'm also thinking about convergence of documentation of kayobe, kolla and kolla-ansible projects. It's true that there's no strict connection between kayobe and other two and kolla containers can be used without kolla-ansible playbooks. But the real benefit the user can get is to use all three projects together. But let's leave that for the second phase.
> >
>
> I'm not so sure about converging them into one set of docs. They are
> each fairly separate tools. We added a short section [6] to each
> covering related projects. Perhaps we should make this a dedicated
> page, and provide more information about the Kolla ecosystem?
>
> [6] https://docs.openstack.org/kolla/latest/#related-projects
>
> >
> >
> > So please comment on this proposal. Do you think it's going in the right direction? If yes, I can refine it.

Following up on this, we discussed it in this week's IRC meeting [1].
We agreed that a good first step would be a simple refactor to remove
the artificial user/admin split. Some more challenging additions and
reworking could follow that, starting with the intro/architecture
sections.

[1] http://eavesdrop.openstack.org/meetings/kolla/2021/kolla.2021-06-02-15.02.log.html#l-136

> >
> >