Jump to: navigation, search

Difference between revisions of "Documentation/Liberty"

(→‎Cross-Project Workshop)
(→‎API Docs Workshop)
 
(16 intermediate revisions by one other user not shown)
Line 20: Line 20:
 
* Grant core access to docs liaisons
 
* Grant core access to docs liaisons
  
−
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).
+
== Ops Documentation Workshop ==
−
I also don't see how it's useful if admin can find the guide for Juno when they're using Juno
+
 
 +
''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.
  
−
Who reads the docs?
+
''Actions''
−
What documentation is missing? -- more effective / useful troubleshooting information (neutron troubleshooting in Ops Guide is the best of what's out there currently)
+
* Document use cases (with help from ops)
−
We should discuss the future of the OpsGuide... I think at the moment it needs some more love. Printed books don't last long. Consolidate remaining useful material into admin and user guides? I'm not married to the idea of creating a separate Troubleshooting Guide; I think there's need for that type of information in the Installation / Admin / User Guides.I still think there's too much cross-information that confuses people as to which doc contains which content. The content to some extent has to be role specific: the installation process is different from the administrator role which is different from the operations role - and to my point, each one of these has unique troubleshooting steps. (Although I do agree with you regarding the potential for confusion, based on first-hand experience ;-) ) That may play into the discussion about service vs role.
+
* 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 ==
 +
Etherpad: https://etherpad.openstack.org/p/Documentation__API_Work_Session
  
−
Ironic documentation is placed inside the ironic repository itself (for operators and developers) But they don't think the ops docs are great and would like them to be improved. Writing docs is hard and maintenance is harder. As the big tent grows, docs team cannot keep up with added content. Ironic docs are RST format. Can we have 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?
+
We discussed the current state of the API reference docs as being WADL and wanting to move away from that for API reference documentation.
  
−
Can we use the depends-on feature of gerrit to ensure that a doc patch has to land if a code patch lands? (Can't have two-way dependency.)
+
Russell Sims brought a sample of using Python routes, pointing at the Cinder repository, and building a JSON file containing all the possible resources, requests, and responses from the Cinder API. He can then build Swagger JSON/YAML from that automation.  
−
 - can we use RST includes between 2 projects (master in openstack-manuals that would include RST files from project repositories?)
 
−
The current <project>/doc/source conf.py does contain the intersphinx extension which allows for :ref: directives, but doesn't do includes that I know of technically. I believe Cloud Foundry has a cross-repo solution for docs. Someone should deep-dive into this post-merge build. (Federating the documentation.)
 
−
One of the problems we see in keystone is everyone wants to put docs in our developer docs. Because admin guide is missing lots of content. Also keystone devs write a lot of great blog entries but the docs continue to be lacking for the "Identity Administrator" 
 
−
 - Maybe try to consolidate books to eliminate confusion as to where stuff goes? I think part of the solution is pushing doc review burden to the project teams themselves.
 
  
−
Workflow to build documentation on local systems is maybe still too complex. Agreed, once we dump docbook it'll be all RST/Sphinx. Is it github/tox/Python that's a barrier? If a developer can "tox -egendocs" and magic happens that should be enough (along with RST format files to edit). Should we add a tox environment to build the docbook documents? There is, if I understand. It is buildlang I think. The documentation should be improved. Yes please (maybe there is and I dont know) -- so, "tox -egendocs" is the global entrypoint for all of the service projects' developer docs. If the doc teams doc project uses a different entrypoint .... that makes it harder for developers to find.
+
We agreed there are a few places where a research spike is required:
  
−
it's tox -e docs <-- this only builds the RST guides
+
* There are some projects that do not use routes and use flask instead (sahara) or pecan (ceilometer). For pecan, there's a Swagger generator available.
  
−
it's tox -e checkbuilds... it should be documented if nobody of us knows it :) Just added to https://wiki.openstack.org/wiki/Documentation/HowTo#Building_Output_Locally (have been meaning to do so!)
+
* Microversions in use by Nova are going to need an extra navigation to let users find all the versions possible. An example of version comparisons https://libgit2.github.com/libgit2/#HEAD is likely what we want.
  
−
https://wiki.openstack.org/wiki/NEUTRON-IPV6-MANUAL Please note it is now ready for +1's
+
* Changes to the API will need to be monitored in the continuous integration pipeline to ensure that API changes are intentional.
  
−
To summarize:  (is it ok? any comment?)
+
* Nova server actions and Heat actions will difficult to document this way due to having multiple routes available for the /actions resource.
−
Doc special team will check some new doc tools, which can manage dev docs & manual easyly. 
 
−
Cross-project liaisons will have a core access to documentations. 
 
  
−
== Ops Documentation Workshop ==
+
* We need to determine how to make an excellent developer guide with both narrative, conceptual, and reference information that fits well with the rest of the developer.openstack.org site.
  
−
== API Docs Workshop ==
+
Anne will work with Russell on getting his code uploaded where we can all work on it.
  
 
== Blueprint Workshop ==
 
== 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 ==
 
== 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 ==
 
== Team Structure Session ==
 +
 +
''Observations''
 +
* We have a huge bug backlog. Requires regular pruning and more active bug tracking.
 +
* Confusion about how to best review and triage
 +
* Should Training Guides be its own group, separate to docs? Let's leave it for now, but assess over time.
 +
* Few active core members, especially outside US timezones. Currently have 12 core, reviewed every six months between releases; could go to every 3 months. Evaluation based on reviews, commits, whether the quality of the review is considered high or just cursory, using these stats: http://stackalytics.com/report/contribution/documentation/30 and http://stackalytics.com/report/contribution/documentation/90
 +
 +
 +
''RFEs''
 +
* Need a better way to handle DocImpact bugs, potentially using Jeepyb?
 +
* Update https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines and integrate with HowTo. Also need section for contributors with ESL
 +
* Need a better/more transparent process for making core
 +
* Need to encourage more corporate contributors, consider ways to provide recognition?
 +
* Want more feedback, consider sending docs people to dev midcycles.
 +
 +
''Actions''
 +
* Ask AJaeger to see if we can subscribe the person who raised a DocImpact patch to the bug.
 +
* Ask Michael Still about https://review.openstack.org/#/c/56158/5/jeepyb/cmd/notify_impact.py
 +
* Talk to docs liaisons about proper use of DocImpact, and also generally encourage more active participation
 +
* Lana to implement a new core process based on metrics+recommendations
 +
* Lana to ask Foundation for funds to send docs people to dev midcycles.
 +
* Lana to talk to the board/TC and Stefano about seeking out corp contributors.
  
 
== Information Architecture Session ==
 
== Information Architecture Session ==
  
 +
''Observations''
 +
* Ops Guide is widely loved. Structure is OK. Slightly out of date.
 +
* HA Guide is being updated and converted to RST
 +
* Security Guide is out of date, confusion over how to get a new Lulu copy
 +
* Arch Guide is being edited for passive voice, but needs an IA overhaul. Currently reads backwards/bottom up (starts with most complex info). Swarm happening in August.
 +
* Install Guide needs to be converted to RST, plus refocused on defcore
 +
* User Guides: Conversion + major reorganisation coming.
 +
* Rewrite the documentation HowTo
 +
* Developer docs: need a plan for helping out devs without taking on maintenance overhead.
  
 +
''RFEs''
 +
* Ops Guide: general tidy up/update for Liberty, plus consider removing Upgrade section (where to put it?)
 +
* Security Guide needs an overhaul. RST conversion to happen > Liberty
 +
 +
''Actions''
 +
* Install Guide - Install Speciality team
 +
* User Guides - User Guide speciality team
 +
 +
== Overview of Liberty Tasks ==
 +
 +
* RST Conversion:
 +
** Install Guide
 +
** Cloud Admin Guide
 +
** HA Guide
 +
** CLI reference
 +
* Restructure user guides
 +
* Increased communication with documentation liaisons, other PTLs, and i18n
 +
* Update the way we select core team
 +
* Update contributor guides
 +
* Clean up the DocImpact bug workflow, and clean out old bugs
 +
* Find a way to get docs people more involved with dev groups (midcycles)
 +
* Increase collaboration with corporate contributors
  
 
== Lessons Learned ==
 
== Lessons Learned ==
 +
 +
* Have the workshops after the fishbowls. We needed to have those discussions before work could start.
 +
* The meetup was a great opportunity for people to drop in, especially if they had missed sessions earlier in the week
 +
* The number of sessions was about right
 +
* The ops and cross-project sessions were valuable: people came to them who wouldn't normally come to a docs session

Latest revision as of 14:27, 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

Etherpad: https://etherpad.openstack.org/p/Documentation__API_Work_Session

We discussed the current state of the API reference docs as being WADL and wanting to move away from that for API reference documentation.

Russell Sims brought a sample of using Python routes, pointing at the Cinder repository, and building a JSON file containing all the possible resources, requests, and responses from the Cinder API. He can then build Swagger JSON/YAML from that automation.

We agreed there are a few places where a research spike is required:

  • There are some projects that do not use routes and use flask instead (sahara) or pecan (ceilometer). For pecan, there's a Swagger generator available.
  • Microversions in use by Nova are going to need an extra navigation to let users find all the versions possible. An example of version comparisons https://libgit2.github.com/libgit2/#HEAD is likely what we want.
  • Changes to the API will need to be monitored in the continuous integration pipeline to ensure that API changes are intentional.
  • Nova server actions and Heat actions will difficult to document this way due to having multiple routes available for the /actions resource.
  • We need to determine how to make an excellent developer guide with both narrative, conceptual, and reference information that fits well with the rest of the developer.openstack.org site.

Anne will work with Russell on getting his code uploaded where we can all work on it.

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


Actions Documents to be converted:

Team Structure Session

Observations

  • We have a huge bug backlog. Requires regular pruning and more active bug tracking.
  • Confusion about how to best review and triage
  • Should Training Guides be its own group, separate to docs? Let's leave it for now, but assess over time.
  • Few active core members, especially outside US timezones. Currently have 12 core, reviewed every six months between releases; could go to every 3 months. Evaluation based on reviews, commits, whether the quality of the review is considered high or just cursory, using these stats: http://stackalytics.com/report/contribution/documentation/30 and http://stackalytics.com/report/contribution/documentation/90


RFEs

  • Need a better way to handle DocImpact bugs, potentially using Jeepyb?
  • Update https://wiki.openstack.org/wiki/Documentation/ReviewGuidelines and integrate with HowTo. Also need section for contributors with ESL
  • Need a better/more transparent process for making core
  • Need to encourage more corporate contributors, consider ways to provide recognition?
  • Want more feedback, consider sending docs people to dev midcycles.

Actions

  • Ask AJaeger to see if we can subscribe the person who raised a DocImpact patch to the bug.
  • Ask Michael Still about https://review.openstack.org/#/c/56158/5/jeepyb/cmd/notify_impact.py
  • Talk to docs liaisons about proper use of DocImpact, and also generally encourage more active participation
  • Lana to implement a new core process based on metrics+recommendations
  • Lana to ask Foundation for funds to send docs people to dev midcycles.
  • Lana to talk to the board/TC and Stefano about seeking out corp contributors.

Information Architecture Session

Observations

  • Ops Guide is widely loved. Structure is OK. Slightly out of date.
  • HA Guide is being updated and converted to RST
  • Security Guide is out of date, confusion over how to get a new Lulu copy
  • Arch Guide is being edited for passive voice, but needs an IA overhaul. Currently reads backwards/bottom up (starts with most complex info). Swarm happening in August.
  • Install Guide needs to be converted to RST, plus refocused on defcore
  • User Guides: Conversion + major reorganisation coming.
  • Rewrite the documentation HowTo
  • Developer docs: need a plan for helping out devs without taking on maintenance overhead.

RFEs

  • Ops Guide: general tidy up/update for Liberty, plus consider removing Upgrade section (where to put it?)
  • Security Guide needs an overhaul. RST conversion to happen > Liberty

Actions

  • Install Guide - Install Speciality team
  • User Guides - User Guide speciality team

Overview of Liberty Tasks

  • RST Conversion:
    • Install Guide
    • Cloud Admin Guide
    • HA Guide
    • CLI reference
  • Restructure user guides
  • Increased communication with documentation liaisons, other PTLs, and i18n
  • Update the way we select core team
  • Update contributor guides
  • Clean up the DocImpact bug workflow, and clean out old bugs
  • Find a way to get docs people more involved with dev groups (midcycles)
  • Increase collaboration with corporate contributors

Lessons Learned

  • Have the workshops after the fishbowls. We needed to have those discussions before work could start.
  • The meetup was a great opportunity for people to drop in, especially if they had missed sessions earlier in the week
  • The number of sessions was about right
  • The ops and cross-project sessions were valuable: people came to them who wouldn't normally come to a docs session
Retrieved from "https://wiki.openstack.org/w/index.php?title=Documentation/Liberty&oldid=81922"