Documenting operations guides

[riverma]

@hookhua had a really interesting idea to potentially coordinate content creation for operational guides for science data system (SDS) software between multiple ongoing NASA SDS projects, such that it may be easier for operator teams to use the software effectively without rewriting content. CC'ing @ldang @mike-gangl @rtapella @niarenaw @pymonger @LalaP @stirlingalgermissen

How can SLIM help in this? Some ideas:

• Would it be helpful to make an operations doc hierarchy structure (i.e. file tree listing) made collaboratively between projects like OPERA SDS, NISAR SDS, SWOT SDS, Unity SDS, HySDS so that there's some coordination on what needs to be in an OPS doc guide and so context switching between projects' OPS guides is easier and more consistent?
• Would it be helpful to make some document templates for key OPS docs written to set a base standard?

Thoughts? Ideas?

[LalaP]

The ideal solution would be to have a centralized procedure/documents for HySDS. For example how to trigger a job, check things on Figaro , etc... is going to be common among all projects using HySDS. Hence if we write the procedures/guide for HySDS in a black box manner so that it does not specify the project file names, or workflows,... then we will have a generic guide. Doing so will help to centralized the effort and prevent multiple edits for when there is a change/new feature/fix/... on HySDS so that the projects would not need to update the same procedure individually for themselves. That way projects would be able to focus on their adaptation layer only.

Doing so also will help to centralize the common errors, failures, and their ideal solutions. Such as when a worker node loses its connection to mozart

[riverma]

That makes a lot of sense @LalaP. Though I imagine there will be subtleties between projects as well that need to be captured outside HySDS core. This makes me think that if we have a consistent hierarchy for an "general" OPS guide, HySDS could create one and projects could adapt that guide structure for their own customizations if necessary, making it easier to switch between guides.

Here's a picture of the current HySDS OPS guide:

Question, can we offer a better way to organize the OPS guide content so that it's easier to navigate, reference from adapted projects, and grow over time? @Scotchester had an interesting link to https://diataxis.fr/ that was useful & mentioned in this ticket that seemed like an interesting way to organize documentation:

[niarenaw]

A (basic) set of the necessary ops guides for OPERA would be the following:

[riverma]

@LalaP @niarenaw - take a look at a ticket I made to try and align with some formatting suggestions Lan has spearheaded at IEMS: nasa/opera-sds-ops#8

If the OPERA project can align with the Ops Guide formatting suggestions of IEMS, that's one step in the right direction. We can post best practices developed potentially here on SLIM.