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. -- [email protected] | TZ: UTC+0530 kadalu.io : Making it easy to provision storage in k8s! _______________________________________________ maintainers mailing list [email protected] https://lists.gluster.org/mailman/listinfo/maintainers
