diff --git a/specs/queens/docs-improvements.rst b/specs/queens/docs-improvements.rst new file mode 100644 index 0000000..1ff4b62 --- /dev/null +++ b/specs/queens/docs-improvements.rst @@ -0,0 +1,189 @@ +Documentation improvements +########################## +:date: 2018-01-08 22:00 +:tags: docs, user stories, walkthrough + +Include the URL of your launchpad blueprint: + * https://blueprints.launchpad.net/openstack-ansible/+spec/example + +People are often confused when they deploy with openstack-ansible, +because they only partially read the documentation, or landed on +the wrong documentation. + +Our deployment guide is already close to what I call a wizard/ +walkthrough, but some parts are easily missed by the deployers. + +On top of that, some very nice advanced documentation are often skipped, or +aren't promoted to their right value. + +Problem description +=================== + +When people land on our deployment guide, which is probably the first +link they access, whether they come from the OpenStack deployment guides +https://docs.openstack.org/pike/deploy/ or from our main developer page +https://docs.openstack.org/openstack-ansible/latest/ , they are facing +the following issues: + +* The landing page is overwhelming, as its a series of link. What do you click? +* The first links clicked (example: https://docs.openstack.org/project-deploy-guide/openstack-ansible/pike/overview.html#) + is just more clicks towards content, and doesn't provide any useful information (the structure is already displayed on the left side of the page). +* Anyone wanting to quickly deploy an openstack-ansible cloud has no way + to know we have an AIO toolkit that could help. +* Anyone wanting to deploy a production cluster with Netapp for example + will most likely not find the appropriate documentation while reading + the deploy guide: It's easy to miss the importance of configuration + on https://docs.openstack.org/project-deploy-guide/openstack-ansible/latest/configure.html#advanced-service-configuration +* The AIO is listed in the "contributor" guides, where it could be available + on any deployment part. +* There is an hard to find "advanced configuration" section, + hidden inside the operations guide. + It should probably be an appendix of the deploy guide. +* We have many overlaps of documentation doing about the same thing, + we should clean things up (for example the advanced configurations + in deploy + operations, the inventory in operations + contributors + + reference) +* There are too many appendices in the deploy guide. Some deserve their + own section. According to the spec http://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html, + "end-user content such as concept guides, advice, tutorials, step-by-step instructions for using the CLI to perform specific tasks, etc." + I think we could technically move scenarios there, as they are step-by-step instructions using shell scripts to perform some specific deploys. +* The role maturity is hard to find. If I were a new deployer, I'd like + to know what I could do with OpenStack-Ansible, and the role maturity + matrix would tremendously help. Sadly I'd never see it in my first + read of the documentation. +* The upgrade guide is our user guide. Why not considering upgrades as + a specific kind of operation? In my opinion, it should be part of + the operations guide, as a major chapter in the operations, in the same + way as minor updates, or scaling the environment. +* We don't motivate people to contribute back directly from the + deploy guide. The last step after verifying that the system works + should be how to extend and contribute to OpenStack-Ansible. +* People could be confused on how to best contribute to the project. + +Proposed change +=============== + +Have some kind of notice at the beginning of the deploy guide, +pointing to our user stories (but advising to read the deploy guide +first). The first user story would be the AIO, with the quickstart +AIO content, for those who want devstack-like easiness, developers, +or for those who want to prototype. +Add more user stories into the user guide, for ceph (test, prod and +ceph-ansible integration), for l3 routed scenarios (tests and prod), +for offline installs. + +Move advanced topics like inventory, container networking, custom +layouts and security principles into a new "reference" section of +the documentation. This section should probably hold the links +to roles' documentations, and should also be linked from the deploy +guide where appropriate. + +Highlight the importance, in the deploy guide, of our advanced +topics (reference). It's important for new deployers to know +where to find documentation on how to do X that's not part of +a user guide. + +At the end of the deploy guide, continue the deploy story by +pointing to our operations and contributions +guide. That could be added into a next steps section. + +The contributors' guide can also be enhanced by listing where +the help is wanted: docs (and their manually testing, like for the +operational guide), bugs (triaging and fixing the low hanging +fruits), test coverage, ... This section could be altered when +the priorities change. + +For improving the reading experience, ensure that each page has +a proper structure: +- Only content should appear in the content part of the page +- The chapters should only be in the upper-left section of + the page ToC, and pointing to this guide chapters, not the whole + documentation items + (avoiding something like https://docs.openstack.org/openstack-ansible/latest/user/index.html) +- The page headers should only be in the lower-left section of the + page ToC. + + +Alternatives +------------ + +Not changing the docs, or partially implementing those changes. + +Playbook/Role impact +-------------------- + +None + +Upgrade impact +-------------- + +None + + +Security impact +--------------- + +None + +Performance impact +------------------ + +None + +End user impact +--------------- + +None + + +Deployer impact +--------------- + +New deployers should be less overwhelmed by Openstack-Ansible + +Developer impact +---------------- + +None + +Dependencies +------------ + +None + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + jean-philippe-evrard + +Other contributors: + * TODO + +Work items +---------- + +Each paragraph of the proposed change can be considered as a work item. + +Testing +======= + +Nothing new. + +Documentation impact +==================== + +This is a docs only change, so this whole change has a documentation impact. +However, because we don't change the structure of the docs themselves, +it should not be very difficult to implement. + +References +========== + +This improvements only happen to improve our readability, and to follow +what's generally expected to find in each of the documentations: + +