[Gluster-Maintainers] [RFC] Some early thoughts about docs.gluster.org

[sankarshan]

I mentioned at the (APAC) Community meeting about posting some
observations around docs.gluster.org and how I think that reducing the
set of available documentation might be a good place to start. This
note is a follow-up to the conversation. I'd like to hear/read
feedback and comments before we take the next step.

Reviewing the current set and state of documentation available from
docs.gluster.org, I've been able to draw a few conclusions

+ the organization of the documents are somewhat aligned with well
known patterns of product documentation - there exists a Quick Start
Guide (QSG); Installation Guide (IG) and Administration Guide (AG). In
addition to these, there is the Developers Guide (DG)
+ the lack of modularity creates a form of inflexibility wherein
content sets across the guides are sometimes inconsistent or not
synchronized
+ there is no specific workflow in place to ensure that important
elements within the guides are kept updated viz. operating system
requirements or, versions of packages etc

The likely reasons for the above situation are perhaps inherent in

+ not having a continuous investment in terms of capacity on
documentation. It has been voluntary, ad-hoc and a couple of good
starts have tapered off
+ having the documentation update not be a blocker to the release
process thus not requiring component maintainers to focus on the
availability of correct content

I do not see this situation change/improve in the near term. And yet,
since we do continue to make releases, we need to balance the reality
of what we have with the idea that we need to do good for our users.
In other words, we have to prevent any way the users could end up (a)
failing to access the bits (b) being unable to configure correctly or,
(c) in a data unavailability or data loss situation

My proposal is that we reduce the number of guides we make available
off docs.gluster.org and instead narrow it down to the absolute
minimum of the QSG. This approach will require us to identify (a) the
opinionated default installation configuration (b) additional items
which need to be included as modules in the QSG. The current content
of the QSG is reasonably concise to take this approach and is likely
the path of least effort.

I have no strong opinions about the DG. Projects should have a DG, but
if that content is not updated or kept current (eg. instructions
around compilation from source are out of date) then we are not being
very helpful. So, that is a topic we need to think over.


-- 
sankarshan at kadalu.io | TZ: UTC+0530
kadalu.io : Making it easy to provision storage in k8s!