Beastly documentation: A SUSE OpenStack Cloud 9 reorg story
Cloud 9 is a complex beast, and so is its documentation. And like any other beast, the documentation needs occasional grooming.
So for the Cloud 9 release, we put a lot of effort not only into documenting new functionality and addressing the existing issues, but also restructuring documentation. Unofficially, we called the project “The Big Doc Reorg”, and we had four key objectives to deliver this April:
- Be consistent across the two flavors of SUSE OpenStack Cloud
- Be consistent with the documentation presentation of other SUSE products
- Reduce duplication of content
- Make it easier to find content
It was a tall order that required significant changes in the documentation’s structure and content. Fortunately for you, we are happy to outline the changes in a fun, friendly blog post! As well as release notes! Hooray!
SOC’s Cloud 9 delivery comprises of our two key deployment methods: Crowbar that utilises Chef, and Cloud Lifecycle Manager (CLM) that utilises Ansible playbooks. So our first, and arguably most important, task was to reorganize the documentation in a way that reflects this. We are pleased to announce that the Crowbar and CLM documentation is now aligned. Each deployment method has an individual Deployment Guide and Operations guide to better serve our administrators and day-to-day operators. We also rearranged and move the content around to make it more logical and easier to find. One of the things we noted with our previous documentation release was that there was almost too much content. Worse yet, some content was out of date. To fix that, we spent time on pruning the content. The result is fewer guides that contain exactly what you are looking for.
Secondly, our long term plan is to rely more on upstream documentation instead of duplicating effort by reproducing content downstream. This plan includes contributing SUSE content upstream so we’ve giving back to the community that gives us so much. As the first step towards this ambitiuous goal, we are fully utilising the upstream OpenStack documentation for our User and Administration content. We have implemented this solution in the Cloud 8 release, improving upon this initial step by publishing the documentation directly from the source for Cloud 9. Huge thank you to Dirk Müller, Jeremy Moffitt, and Gary Smith for the work they’ve done to make the upstream conversion possible. We are still not where we want to be, but we are steadily getting there.
This is, of course, just a brief overview of the work we’ve done so far. For more indepth information, see our release notes.
The documentation team welcomes feedback from all our users. You can submit a bug at bugzilla.suse.com or you can send an email to doc-team@suse.com to let us know how we can improve, or if you’re so inclined, let us know what we’re doing right!
You can find the cloud documentation at our SUSE OpenStack Cloud 9 Documentation page.
This article was co-authored by Cloud documentation team members, Alexandra Settle and Dmitri Popov.
(Visited 12 times, 1 visits today)
Related Articles
Feb 21st, 2023
SUSE Linux Enterprise 15 Service Pack 5 Public Beta is out!
6,203 views
No comments yet