[openstack-dev] [docs][i18n][ptg] Denver PTG Summary for Docs (and i18n)

Petr Kovar pkovar at redhat.com
Wed Sep 20 20:47:20 UTC 2017


Hi all,

Just wanted to share a few notes and a brief summary of what happened in
Denver last week, during the Project Team Gathering, in docs and i18n
shared sessions.

We had a fairly good attendance of 5 to 15 ppl during the first two
days. A number of people primarily working on other projects showed up in
our sessions to chat about common issues and plans. On the other hand, many
of our cores couldn't attend, though I'm hoping if PTG comes closer to
Europe, the attendance will improve.

On a related note, we also welcomed new cores to the team and the Denver
PTG was an opportunity for some of us to meet face to face for the first
time.

The overall schedule for all our sessions with some comments can be found at
https://etherpad.openstack.org/p/docs-i18n-ptg-queens, there's also
https://etherpad.openstack.org/p/doc-future-problems with a more detailed
discussion of some of the items.

To summarize what I found most important:

VISION

We spent a lot of time discussing a new vision document for the docs team,
based on the updated docs team mission statement
(https://review.openstack.org/#/c/499556/). A working draft is available
here:

https://etherpad.openstack.org/p/docs-i18n-ptg-queens-mission-statement

In the coming weeks, we'll transform those notes into a final draft and
share it with the broader community for input.

The next step after this would be to update/rework
https://governance.openstack.org/tc/reference/tags/docs_follows-policy.html.

EOL DOCS AVAILABILITY

Discussed addressing numerous issues related to publishing EOL docs and our
docs retention policy, based on community feedback and many requests. The
plan is to write a retention policy docs spec, resurrect Mitaka docs and add
badges to clearly identify unsupported content, among other things.

HA GUIDE

Work will continue on the guide per the previous plans.

ARCHITECTURE GUIDE

>From Pike, this guide is frozen. Patches still welcome.

OPENSTACK-MANUALS BUGS

To be moved to appropriate projects, if applicable.

CONFIG DOCS

Discussed with several teams, particularly cinder, how to generate
config tables using oslo_config.sphinxext.

REDESIGNING DOCS SITE

A couple of improvements to adjust the site content structure and
overall design was discussed, such as tweaking lists of projects, linking
from series subpages back to the top page, install vs. deployment pages,
linking to projects with no stable branches, redoing our sitemap, switching
to SCSS, improving HTML semantics, etc.

DOCS TOOLING

Doug kindly offered the team and the community to give a presentation
about updated docs tooling:

https://etherpad.openstack.org/p/doc-tool-lunch-and-learn

We'll turn this into a proper doc and share with everybody.

INSTALL GUIDES TESTING

A couple of people and teams showed interest in testing the Pike install
guides (common content + minimal deployment services). To track this
activity, we'll use this wiki page:

https://wiki.openstack.org/wiki/Documentation/PikeDocTesting

TRANSLATIONS

Discussed generating multiple PO files for docs
migrated to project repos, to make translators' lives easier.

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 in particular to Alex
who took most of the notes. I think this PTG was very productive, full of
energy, and intense!

Cheers,
pk



More information about the OpenStack-dev mailing list