Difference between revisions of "Documentation/Liberty"
(→Ops Documentation Workshop) |
|||
| Line 23: | Line 23: | ||
''Observations'' | ''Observations'' | ||
| + | * Docs are confusing, don't know where info is | ||
| + | * Audience type is not clear/well understood | ||
''RFEs'' | ''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'' | ''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 | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | Add | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
== API Docs Workshop == | == API Docs Workshop == | ||
Revision as of 23:33, 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
- 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
Observations
RFEs
Actions
RST Migration Session
Observations
RFEs
Actions
Team Structure Session
Observations
RFEs
Actions
Information Architecture Session
Observations
RFEs
Actions
