From 7baca66b9e4383ada336f69399677a1138103b09 Mon Sep 17 00:00:00 2001 From: Luka Peschke Date: Fri, 26 Oct 2018 11:45:48 +0200 Subject: [PATCH] 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 | 10 + .../refactoring_cloudkittys_documentation.rst | 187 ++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 specs/stein/refactoring_cloudkittys_documentation.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index a442991..6e22b58 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -4,6 +4,16 @@ Cloudkitty Project Specifications ================================= +Stein +===== + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/stein/* + + Pike ==== diff --git a/specs/stein/refactoring_cloudkittys_documentation.rst b/specs/stein/refactoring_cloudkittys_documentation.rst new file mode 100644 index 0000000..a97c39d --- /dev/null +++ b/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