Spec: Refactor CloudKitty's documentation

This is a proposal for the new layout of cloudkitty's documentation,

Once this has been approved and discussed, we'll add some tasks to the
associated story.

Depends-On: https://review.openstack.org/#/c/613339/
Change-Id: I64704d9e78a7c70c66cab3068fbc4addf87783a6
Story: 2004179
Task: 27664

doc/source/index.rst

@@ -4,6 +4,16 @@
 Cloudkitty Project Specifications
 =================================
 
+Stein
+=====
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   specs/stein/*
+
+
 Pike
 ====
 

specs/stein/refactoring_cloudkittys_documentation.rst

@@ -0,0 +1,187 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+======================================
+Refactoring CloudKitty's documentation
+======================================
+
+https://storyboard.openstack.org/#!/story/2004179
+
+CloudKitty's documentation needs to be refactored. This spec aims at proposing
+a new content layout. It is of course subject to discussion, as well
+on storyboard as on gerrit.
+
+Problem Description
+===================
+
+Since Cloudkitty has been through major changes in the last releases, the
+current documentation layout and content causes several problems:
+
+* The layout is not intuitive: many people on IRC ask for information that is
+  available in the documentation, but very hard to find.
+
+* Cloudkitty's architecture as well as the role of each component (fetcher,
+  collector, rating module, storage backend...) is not explained clearly enough.
+  This is a problem for operators, as they don't know how CloudKitty works
+  internally, which is an issue when troubleshooting.
+
+* The configuration of metric collection is very poorly documented, leading most
+  operators to stick to the default ``metrics.yml`` file, without knowing
+  exactly what each entry means.
+
+* The developer documentation is almost non-existent: It only contains
+  information about the v2 storage interface. It should be extended to help
+  contributors.
+
+* The documentation also lacks an FAQ/troubleshooting part: Typical question
+  is "I deployed Cloudkitty with Devstack, why is summary 0 ?".
+
+Proposed Change
+===============
+
+The first thing in the documentation should be a very brief introduction about
+what CloudKitty is and does. Concerning people reading CloudKitty's
+documentation: they can be split into three groups; users, operators/admins,
+and developers. In consequence, proposed top-level sections after the short
+introduction would be the following:
+
+* Common introduction: What's the matter/need Cloudkitty aims to solve ?
+  What's possible ? What's not (yet) ? What will never be supported ?
+
+  In addition to these questions, there should be a general introduction on the
+  different components, their roles and how they interact.
+
+* User documentation: How do I retrieve information through cloudkitty's API ?
+  What kind of information can I get ?
+
+* HTTP API reference. However, reference of the v2 API will be published to
+  ``developer.openstack.org/api-ref`` once it is considered stable.
+
+* Operator documentation: This section should detail the role of each component,
+  and provide information about how to configure it. This is also where
+  information on rating rule creation should live. Operators are also the target
+  audience for the troubleshooting section.
+
+  In opposition to the current approach (with keystone/openstack vs.
+  without keystone/openstack), I believe that this part of the documentation
+  should explain each component one by one: its purpose, how it can be used,
+  existing implementations (list different collectors/fetchers/rating modules,
+  and ideally provide a support matrix), and how it can be configured.
+
+  Example of a usecase where configuration is hard to deduce from the
+  documentation: CloudKitty is used without keystone authentication and collects
+  prometheus metrics. However, in order to collect metrics from gnocchi, the
+  collector needs to authenticate to keystone. How to configure this ?
+
+* Developer documentation: This section should provide implementation details
+  about the different components cloudkitty is made of. It should explain
+  contributors what they need to implement, which interfaces they should use,
+  and how their contribution should be tested. Ideally, this should complete
+  the docstrings of an interface. A (small and probably not complete enough)
+  example of such a documentation can be found here:
+  https://docs.openstack.org/cloudkitty/latest/developer/storage.html
+
+  Here again, the documentation should be split by component.
+
+Alternatives
+------------
+
+I don't have any alternative layouts or contents in mind, but proposals are
+of course welcome!
+
+Data model impact
+-----------------
+None
+
+REST API impact
+---------------
+
+None, except maybe a better documentation of the API.
+
+Security impact
+---------------
+
+None
+
+Notifications Impact
+--------------------
+
+None
+
+Other end user impact
+---------------------
+
+End users and contributors will have a better understanding of the project.
+
+Performance Impact
+------------------
+
+None
+
+Other deployer impact
+---------------------
+
+Better understanding of the projet, troubleshooting made easier.
+
+Developer impact
+----------------
+
+Better understanding of the projet, contributing made easier.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Luka Peschke is assigned for the work on the spec, and the integration of the
+new layout to the doc. Work on the content of the documentation will be
+dispatched once the spec has been reviewed, corrected and merged.
+
+Primary assignee:
+  peschk_l
+
+Other contributors:
+  None
+
+Work Items
+----------
+
+* Apply the new layout to cloudkitty's documentation
+
+* Write an introduction with a few schemas
+
+* Improve the documentation (sub-)section by (sub-)section, with one commit/task
+  couple per subject.
+
+Dependencies
+============
+
+None
+
+Testing
+=======
+
+None
+
+Documentation Impact
+====================
+
+The documentation will be completely modified, and a lot of content will be
+added.
+
+References
+==========
+
+* Glance documentation, which is a good example of a documentation organised per
+  user profile: https://docs.openstack.org/glance/latest/
+
+* Some support matrixes:
+
+  - Elastic product / OS: https://www.elastic.co/support/matrix
+
+  - Kubernetes persistent volumes access modes:
+    https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes