Jump to: navigation, search

Documentation/Liberty

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

RFEs

Actions


sched.org content: https://etherpad.openstack.org/p/YVR-ops-docs

"What can we help you with?"

Use cases "Drive what you're documenting from a knob standpoint" Difference between "operator" and "user"? Working on defining this Operator: installs, deploys Admin: maintains, uploads images User: actually spinning up VMs Distinction/similarity between Operator/Admin: "Dude, my instance isn't running" - are they the same person/class of people? Why discuss this? Organizing the documentation by audience

Admin/ops docs assume you've already installed

Install Guide can be thought of as an install training guide. Install guide -> Security Guide, HA, Admin (ideal workflow) "What are my next steps?" - something we need to add to the install guide?

Which guide contains which inormation?

Use Cases - How do I install with HA (step me through it).

Add to Install Guide: Next steps ("where do I go from here? What do I do next?) Things like other guides, increased complexity, other OpenStack services.

Organization by role or by service? Looking for flags to set in Neutron config - how to find?


config-ref not enough detail about the file/section in which a config flag should go and on which node should the flag be modified


Top-level guide: a tree of service, config files, possible things you can put in - a reference. We have one that's auto-generated Flowchart?

One or two sentence description under each title on docs site

Q: Is there post-install direction on how to test your cloud (other than by success/failure on spinning up a VM)? There are (should be) checks/tests at the end of each Install Guide section.

Who wants to document the use cases?

API Docs Workshop

Observations

RFEs

Actions

Blueprint Workshop

Observations

RFEs

Actions

RST Migration Session

Observations

RFEs

Actions

Team Structure Session

Observations

RFEs

Actions

Information Architecture Session

Observations

RFEs

Actions


Lessons Learned