Revision as of 03:17, 27 May 2015

Liberty Design Summit Wrap-up

Cross-Project Workshop

Observations

• sorting by user type (ops, admin, etc) is ineffective
• there is a generally-held assumption that building docs is difficult.

RFEs

• Need to talk about trying to support multiple releases in one doc. It's a lot of work when you're way behind on docs (e.g., for Keystone).
• more effective / useful troubleshooting information (neutron troubleshooting in Ops Guide is the best of what's out there currently)
• socialise info about RST and tox (as oposed to docbook and maven)

Actions

• discuss the future of the OpsGuide
• IMplement a post-publish job that copies/links/syndicates Ironic's in-tree ops guide to the admin-cloud-guide? Can we do something similar for every project?
• Discuss with doc liaisons how to get docs assistance with docs in their repo, without bringing content into docs repo (maintenance overhead stays with dev, not doc)
• Ensure tox is well-documented (seems to be little understood)
• Grant core access to docs liaisons

Ops Documentation Workshop

Observations

• Docs are confusing, don't know where info is
• Audience type is not clear/well understood

RFEs

• make the docs more use-case based, rather than audience type (what's the difference between an operator and a user?)
• Add to Install Guide: Next steps ("where do I go from here? What do I do next?)
• Top-level guide: a tree of service, config files, possible things you can put in - a reference.
• Flowchart of steps to install/configure/manage
• There are (should be) checks/tests at the end of each Install Guide section.

Actions

• Document use cases (with help from ops)
• Add a sentence or two description to each doc under the title on the main page (which doc contains what information?)
• make audience types more defined, better communicated

API Docs Workshop

Observations

RFEs

Actions

Blueprint Workshop

Installation Guide

Contact: Karin Levenstein <karin.levenstein@rackspace.com>

Blueprint: https://blueprints.launchpad.net/openstack-manuals/+spec/installguide-liberty

Spec WIP: https://review.openstack.org/#/c/183138/

Notes

• XML in stable/kilo branch.
• Cut kilo branch after YVR, freeze Docbook in master (don't take docbook patches to the install-guide in master branch)
• Migrate core only for now, including conditional text
• Longer install guide can be glued together after migration. Top priority is what we have now.
• Drop Debian until after migration, and until we have a committed resource.

Actions

• Lana to check with Mirantis about a dedicated Debian resource
• Install Guide speciality team to work on blueprint/spec
• Lana to contact PTLs to inform

Networking Guide

Contact: Nick Chase <nchase@mirantis.com>, Matt Kassawara <mkassawara@gmail.com>

Notes

• Needs finishing, plus changes for Liberty
• Dan Sneddon <dsneddon@redhat.com> interested in contributing for Liberty
• missing blueprints

Actions

• Matt & Nick to write blueprint

User Guides

Contact: Joe Robinson <Joseph.r.email@gmail.com>, Brian Moss <kallimachos@gmail.com>

Blueprint: https://blueprints.launchpad.net/openstack-manuals/+spec/reorganise-user-guides

Notes

• Need to convert Cloud Admin Guide to RST, then reorganise on user type
• the Admin User Guide should disappear, with its content split between the Cloud Admin Guide and the End User Guide. Those two guide could then probably be renamed to just Admin Guide and User Guide.
• Emett Speer <speer.emett@gmail.com> interested in contributing for the conversion

Actions

• Start work!

HA Guide

Contact: Meg McRoberts <dreidellhasa@yahoo.com>

Blueprint: https://blueprints.launchpad.net/openstack-manuals/+spec/improve-ha-guide

Spec: http://specs.openstack.org/openstack/docs-specs/specs/liberty/ha-guide.html https://review.openstack.org/#/c/178427/

Notes

• RST conversion
• General updates
• Merged structure in RST
• Content sprint during the summit

Actions

• Let translators know when ready to start

RST Migration Session

Observations

• Documents already converted:
  • End User Guide http://docs.openstack.org/user-guide/
  • Admin User Guide http://docs.openstack.org/user-guide-admin/
  • Networking Guide http://docs.openstack.org/networking-guide/
  • Writing your First OpenStack Application Guide http://developer.openstack.org/firstapp-libcloud/
  • Glossary (automatically converted)
• Metrics here: https://docs.google.com/spreadsheets/d/10HD6iW1CtfB1qT2wVODYiHdC0ysr4xw392VCqHB-aaY/edit?usp=sharing
• Config Reference cannot be converted yet, because there are docbook books importing the generated tables at the moment - in other words, it's mixed generated and written content, so the generator needs to be updated to make RST tables and the written content needs to be converted to RST, but not now. gpocentek to handle RST tables.

Actions Documents to be converted:

• Installation Guide: See https://wiki.openstack.org/wiki/Documentation/InstallGuide and https://review.openstack.org/#/c/183138/
  • Kilo branch stays in docbook, master becomes RST
  • Covers only core projects (nova, cinder, glance, keystone, neutron, swift), no content changes. Longer install guide that projects maintain can come later.
  • Karin (with the Install Guide speciality team) to project manage
• Cloud Admin Guide
  • Convert guide first, then re-architect w/ Admin guide (please consider translation team when communicating)
  • Not based on a release cycle
  • Brian Moss & Joseph Robinson (with User Guide speciality team) to do this work
• CLI Reference
  • Christian will take care of migration of the CLI Reference to RST.
  • Change the autogenerate template for config reference - it's basically single-point-of-control. See https://github.com/openstack/openstack-doc-tools/blob/master/autogenerate_config_docs/autohelp.py#L60 and https://github.com/openstack/openstack-doc-tools/blob/master/autogenerate_config_docs/autohelp.py#L81

Team Structure Session

Observations

RFEs

Actions

Information Architecture Session

Observations

RFEs

Actions

Lessons Learned