Difference between revisions of "Documentation/Liberty"
(Created Page) |
(→Cross-Project Workshop) |
||
| Line 3: | Line 3: | ||
== Cross-Project Workshop == | == 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 | ||
| + | |||
| + | 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). | ||
| + | I also don't see how it's useful if admin can find the guide for Juno when they're using Juno | ||
| + | |||
| + | Who reads the docs? | ||
| + | What documentation is missing? -- more effective / useful troubleshooting information (neutron troubleshooting in Ops Guide is the best of what's out there currently) | ||
| + | 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. | ||
| + | |||
| + | |||
| + | 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? | ||
| + | |||
| + | 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.) | ||
| + | - 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. | ||
| + | |||
| + | it's tox -e docs <-- this only builds the RST guides | ||
| + | |||
| + | 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!) | ||
| + | |||
| + | https://wiki.openstack.org/wiki/NEUTRON-IPV6-MANUAL Please note it is now ready for +1's | ||
| + | |||
| + | To summarize: (is it ok? any comment?) | ||
| + | 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 == | == Ops Documentation Workshop == | ||
Revision as of 23:25, 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
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). I also don't see how it's useful if admin can find the guide for Juno when they're using Juno
Who reads the docs? What documentation is missing? -- more effective / useful troubleshooting information (neutron troubleshooting in Ops Guide is the best of what's out there currently) 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.
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?
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.) - 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.
it's tox -e docs <-- this only builds the RST guides
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!)
https://wiki.openstack.org/wiki/NEUTRON-IPV6-MANUAL Please note it is now ready for +1's
To summarize: (is it ok? any comment?) 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.
