Ian Y. Choi and I already shared a summary of docs and i18n updates from the Stein Project Teams Gathering with the openstack-dev mailing list, but I also wanted to post the updates here for wider distribution. So, here comes what I found the most interesting out of our docs- and i18n-related meetings and discussions we had in Denver from 10 through 14 September.
The overall schedule for all our sessions with additional comments and meeting minutes can be found in OpenStack Etherpad.
First things first, so the following is our obligatory team picture (with quite a few members missing); picture courtesy of OpenStack Foundation folks:
Operators documentation
We met with the Ops community to discuss the future of Ops docs. The plan is for the Ops group to take ownership of the operations-guide (done), ha-guide (in progress), and the arch-design guide (to do).
These three documents are being moved from the openstack-manuals repository to their own repos, owned by the newly formed Operations Documentation SIG.
See also ops-meetup-ptg-denver-2018-operations-guide for more notes.
Documentation site and design
We discussed improving the docs.openstack.org site navigation, guide summaries (in particular, install-guide), adding a new index page for project team contrib guides, and more. We met with the OpenStack Foundation staff to discuss the possibility of getting assistance with site design work.
We are also looking into accepting contributions from the Strategic Focus Areas folks to make parts of the docs toolchain like openstackdocstheme more easily reusable outside of the official OpenStack infrastructure. Support for some of the external project docs has already landed in git.
We got feedback on our front page template for project team docs, with Ironic being the pilot for us.
We got input on restructuring and reworking specs site to make it easier for users to understand that specs are not feature descriptions nor project docs, and to make it more consistent in how the project teams publish their specs. This will need to be further discussed with the folks owning the specs site infra.
Support status badges showing at the top of docs.openstack.org pages may not work well for projects following the cycle-with-intermediary release model, such as swift. We need to rethink how we configure and present the badges.
There are also some UX bugs present in badges (for instance, bug 1788389).
Translations
We met with the infra team to discuss progress on translating project team docs and, related to that, generating PDFs.
With the Foundation staff, we discussed translating Edge and Container whitepapers and similar material.
More details in Ian’s notes.
Reference, REST API docs and Release Notes
With the QA team, we discussed the scope and purpose of the /doc/source/reference documentation area in project docs. Because the scope of /reference might be unclear and can be used inconsistently by project teams, the suggestion is to continue with the original migration plan and migrate REST API and possibly Release Notes under /doc/source, as documented in doc-contrib-guide.
Contributor Guide
The OpenStack Contributor Guide was discussed in a separate session, see FC_SIG_ptg_stein for notes.
Thanks!
Finally, I’d like to thank everybody who attended the sessions, and a special thanks goes to all the PTG organizers and the OpenStack community in general for all their work!
Quelle: RDO
Published by