Documentation/Liberty
Contents
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?