Difference between revisions of "Documentation/Liberty"
(→Cross-Project Workshop) |
(→Ops Documentation Workshop) |
||
Line 21: | Line 21: | ||
== Ops Documentation Workshop == | == 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 == | == API Docs Workshop == |
Revision as of 23:27, 25 May 2015
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?