2022-11-04 - Sys Ops & Management SIG Agenda and Meeting notes

As an aftermath of the SysOps SIG WolfCon session (the top pain points) and coming out of the Pain Points discussion that we have led in this SIG, I would like to draw the attention to the TC Pain Points compilation. "docs.google.com/document/d/14UNMGb_zVvSGBYtTjyb47c_FG1WmOSJGSkc42A5D0Ks/edit"

Now that we have collected and categorized these pain points, the question is of course, what can be done to appease the pain.

Clearly, this SIG can not appease much of Okapi complexity and module inter-dependencies, just to name two examples.

But what we might realistically accomplish could be operational documentation. Yes, it means that we will write some parts of the documentation ourselves

Let us first classify what we can do and what we can not do and then pick up some responsibilities:

Places and types of documentation relevant for a FOLIO installation or upgrade or other forms of system administration (migrations, performance tuning, logging, ...) :

• Documentation of Elasticsearch and Kafka : out of scope
• "Insufficient API and JSON documentation"
  • is this meant to be what is under dev.folio.org ? Yes. Maybe SysOps SIG can report nuisances/defects to the dev ops folks (who I guess are in charge of maintaining this)
    • document workflows; how to do a fiscal year rollover ? If you send a request, you need to post a payload first (for example)
    • There is FOLIO ProTipps
    • docs.folio.org: The links are not documented. Single Server installation sends you to the Lotus release, but it doesn't tell you.
• Module documentation on dockerhub: folioci's Profile | Docker Hub
  • does this have deficits ?
  • Docker Hub pulls documentation from the modules' documentation on github. But the github documentation is not always complete (e.g. mod-remote-storage)
  • in the module descriptor, it is not always complete
  • Tipps & Tricks section: Individual Apps - Information, Tips, and Tricks some of it is in docs.folio.org, some is not
  • The Release Notes are not always carried forward. They still apply in newer releases. You are supposed to remember it.
  • can we contribute to improve these deficits (if any) ?
• Release Notes (Morning Glory (R2 2022) Release Notes - Releases - FOLIO Wiki, Lotus (R1 2022) Release Notes - Releases - FOLIO Wiki)
  • Shall SysOps people be involved in the "Changes and Required Actions" table - at least with testing and giving feedback before this is being published ?
  • Should someone from SysOps be involved in setting up the to-be-released system - prior to release ? If yes, can we commit to this ?
  • Installation procedures (single server, kubernetes, Vagrant) should be synchronized with the release notes, and not be published long after it
  • Jason works with Erin in upgrading this. At the moment, Product Owners and Developers write this. We should report deficiencies. Product Owners' responsiability otherwise.
• Notifications of changes on the single modules; not being reported on the Release Notes. The NEWS.md and README.md files on the github site of the module. For example for mod-inventory: mod-inventory/NEWS.md at master · folio-org/mod-inventory (github.com) , mod-inventory/README.MD at master · folio-org/mod-inventory (github.com)
  • are these changes being sufficiently and understandably described ? Yes
  • in my opinion, awareness about these pages is not big enough. In other words, many people do not know these pages or are not reading them (because no one points them to them).
  • should system operators actively contribute to these pages in order to facilitate installation/operation for other system operators ? I know we can do pull request. Maybe a better question: Should system operators be notified (in some way) if something cganges on these pages ?
• Single Server Installation Documentation (Ingolf is maintaining this). docs/content/en/docs/Getting started/Installation at main · folio-org/docs (github.com)
  • • Ingolf is doing this but can not commit to do this forever. Upgrades from Release Notes to single server installtion get lost in the shuffle.
• "Kubernetes Example"  (Jason is maintaining this) folio-install/alternative-install/kubernetes-rancher/TAMU at master · folio-org/folio-install (github.com)
• Institutional documentation, published on the SysOps Wiki space: Deployment Environments in SIG members' institutes - System Operations and Management SIG - FOLIO Wiki — everyone is encouraged to further populate this and keep this up to date!
• Also here: (institutional documentation, upgrades): In-place upgrades and Folio-to-Folio release data-migration - System Operations and Management SIG - FOLIO Wiki
  • upgrade notes; but deprecated (old)
• Another collection of Existing Documentation : Let's go through this and see where we can improve ! Includes Helm Charts and Okapi Guide & Reference.

Bullet points from the Pain Points document

• Improve foundational documentation regarding architecture and technical philosophy. => This means what ?
• Provide consistent and project-wide operational documentation on a module-by-module basis
• Improve release upgrade documentation

That was a long list and is all I can think of at the moment!  

Can you think of other places or types of documentation that we need, that needs to be improved and that SysOps people might be able to contribute (or at least communicate defiencies) ?

To institutionalize our efforts, I think these actions have to become part of the official FOLIO documentation working group. So far, only what is under Install FOLIO | FOLIO Documentation is controlled, versionized and kept up to date by this group.