Adopt Documentation to Five-Cluster-Operation
With the installation of Barnard, decommission of the Haswell partition, and some re-cabling, we will not have one system anymore, but five ones. Each will be operated as independent cluster. Thus, we have to make a plan, how we plan to differentiate the documentation w.r.t. to these five clusters.
The timeline is as follows:
- between 27.11. - 10.12.2023 the following systems will not be available due to refurbishment: Romeo, Julia, Alpha Centauri, Power9
- on 11.12.2023 Taurus will be decommissioned for good,
- /lustre/scratch + /lustre/ssd will be turned off on 03.01.2024 for good (no data access afterwards!)
Option 0
Create a separate documentation for each cluster. Each cluster specific documentation has its very own subtree in the TOC.
Pros
- Since the user has to decide for a cluster before running any job and experiments, this would meet this decision.
- When a cluster is switched-off, we can easily move the documentation to the archive
- Cluster-specific documentation
- Adopt available pages to certain cluster, e.g., if a certain service is not available on a cluster, we can delete it
- Single-cluster-users might get less confused, because they only read very tailored documentation
Cons
- Lot of redundant information
- Five-fold increase in number of pages and attachments
- Maintainability: Keeping five cluster documentations up-to-date is a huge effort
- How to adopt the search?
- Difficult to compare differences and overlaps for multi-cluster-users
Option 1
Stick to one documentation and adopt the individual pages. Differences can be encapsulated in tabs or collapsible admonitions (e.g., notes).
Pros
- Less rework compared to option 0
- Less maintenance effort compared to option 0
Cons
- Requires thoroughly planed guide lines and rules for differentiation (w.r.t. code blocks, prosa, etc.)
- If a cluster is switched-off, what information will be transferred to the archive?
Decision Helpers
- How does other sites with multiple cluster handle it?
- How different will our five cluster become from the user's perspective?
- Option 1: What style elements can be used for differentiation within a single page? (What about tags?)