Open Stack

Hi all,

Just wanted to share a summary of docs- and i18n-related meetings
and discussions we had in Denver last week during the Stein Project
Teams Gathering.

The overall schedule for all our sessions with additional comments and
meeting minutes can be found here:

https://etherpad.openstack.org/p/docs-i18n-ptg-stein

Our obligatory team picture (with quite a few members missing) can be
found here (courtesy of Foundation folks):

https://pmkovar.fedorapeople.org/DSC_4422.JPG

To summarize what I found most important:

OPS DOCS

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 openstack-manuals to their own
repos, owned by the newly formed Operations Documentation SIG.

See also
https://etherpad.openstack.org/p/ops-meetup-ptg-denver-2018-operations-guide
for more notes.

DOCS SITE & DESIGN

We discussed improving the site navigation, guide summaries (particularly
install-guide), adding a new index page for project team contrib guides, and
more. We met with the 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.

We got feedback on 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.o.o 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 for the badges
(https://bugs.launchpad.net/openstack-doc-tools/+bug/1788389).

TRANSLATIONS

We met with the infra team to discuss progress on translating project team
docs and, related to that, PDF builds.

With the Foundation staff, we discussed translating Edge and Container
whitepapers and related material.

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 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 described
in https://docs.openstack.org/doc-contrib-guide/project-guides.html. 

CONTRIBUTOR GUIDE

The OpenStack Contributor Guide was discussed in a separate session, see
https://etherpad.openstack.org/p/FC_SIG_ptg_stein for notes.

THAT'S IT?

Please add to the list if I missed anything important, particularly for
i18n.

Thank you to everybody who attended the sessions, and a special thanks goes
to all the PTG organizers!

Cheers,
pk