Merge "Improve user experience by simplifying the guides"
This commit is contained in:
commit
677ea7421b
|
@ -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:
|
||||
|
||||
|
Loading…
Reference in New Issue