Glossary section #104
Glossary section #104
Conversation
AshleyCliff
left a comment
AshleyCliff
left a comment
There was a problem hiding this comment.
This is great work! I've made some suggestions around formatting and added a few resource links.
reference/glossary.md
Outdated
| Apptainer | ||
| HPC-focused container runtime. Formerly Singularity. | ||
| Refers to both the software and the corresponding charm. | ||
| Resources: | ||
| - [Apptainer - Portable, Reproducible Containers](https://apptainer.org/) | ||
| - [Charmhub | apptainer](https://charmhub.io/apptainer) |
There was a problem hiding this comment.
| Apptainer | |
| HPC-focused container runtime. Formerly Singularity. | |
| Refers to both the software and the corresponding charm. | |
| Resources: | |
| - [Apptainer - Portable, Reproducible Containers](https://apptainer.org/) | |
| - [Charmhub | apptainer](https://charmhub.io/apptainer) | |
| Apptainer | |
| HPC-focused container runtime. Formerly Singularity. | |
| Resources: | |
| - [Apptainer - Portable, Reproducible Containers](https://apptainer.org/) | |
| - [apptainer charm](https://charmhub.io/apptainer) |
There was a problem hiding this comment.
Rather than repeat the 'software and corresponding charm' statement in a variety of places, I think simply pointing to both the source and the charm in the resources makes that point with less words.
I'd suggest something more like this for each of the places with that statement.
reference/glossary.md
Outdated
| Amazon Web Services (AWS) | ||
| A cloud platform provided by Amazon that can be used to host Charmed HPC. See the [AWS website](https://aws.amazon.com/) for more information. | ||
| A cloud platform provided by Amazon that can be used to host Charmed HPC. |
There was a problem hiding this comment.
I both like and don't like that this refers to its use in relation to Charmed HPC. For a glossary specifically, we might want to keep it to the general details and let our other docs show how it relates to Charmed HPC. @NucciTheBoss thoughts?
There was a problem hiding this comment.
For the glossary, let's keep the definitions general and not specific to Charmed HPC unless it's necessary like "what's slurm-ops". We should treat our glossary like Wikipedia where the linked resources are not tightly related to the original topic.
This way we don't have to worry about Charmed HPC "detracting" from the goal of adding topics like AWS and Slurm to the glossary which is to help people better understand the external technologies we are working with. Our docs will then demonstrate the relationship these technologies have with Charmed HPC. E.g. "What's this AWS Charmed HPC is being deployed on. Ah! Amazon Web Services"
| Ceph | ||
| Distributed storage system that provides object, block, and file storage. | ||
There was a problem hiding this comment.
| Ceph | |
| Distributed storage system that provides object, block, and file storage. | |
| Ceph | |
| Distributed storage system that provides object, block, and file storage. | |
| Resources: [ceph](https://ceph.io/en/), [Charmed ceph](https://ubuntu.com/ceph/docs) |
There was a problem hiding this comment.
Check that those are the most appropriate places to link to. Thoughts on having the links on a single line? It would condense the term blocks a bit which might help with distinguishing one term block from the next. (If we like this, we should do it for all of them)
There was a problem hiding this comment.
@AshleyCliff we should link to the microceph docs instead as we're using microceph and not the legacy Charmed Ceph.
There was a problem hiding this comment.
I wasn't sure which one we were using tbh - and if I'm not sure, we should anticipate users being in a similar boat and spell out the microceph to ceph relationship
There was a problem hiding this comment.
I like the links on a single line with how it improves the layout but it can be tricky to see where one link ends and the next begins with a comma between them. I think putting a • between them makes it a bit clearer. I'll make the change and see what people think
There was a problem hiding this comment.
Having said that. this still seems a bit clustered:
I'll change it to the following instead since the 🌐 makes it crystal clear where links begin:
| CephFS | ||
| POSIX-compliant file system interface that runs on top of a Ceph storage cluster. |
There was a problem hiding this comment.
| CephFS | |
| POSIX-compliant file system interface that runs on top of a Ceph storage cluster. | |
| CephFS | |
| POSIX-compliant file system interface that runs on top of a Ceph storage cluster. | |
| Resources: [Ceph file system](https://docs.ceph.com/en/latest/cephfs/) |
There was a problem hiding this comment.
We should also include a link here to the microceph docs for CephFS and maybe the CephFS charm. Thoughts @dsloanm?
There was a problem hiding this comment.
I'll give MicroCeph its own glossary entry since it's a separate entity to Ceph and CephFS. It's just the (very strongly) recommended path to achieving Ceph.
Co-authored-by: Ashley Cliff <ashley.cliff@canonical.com>
|
The latest commits should address comments. Let me know your thoughts on use of 🌐 for the resource links. I think it delimits the links clearly but the emoji may be too distracting |
AshleyCliff
left a comment
AshleyCliff
left a comment
There was a problem hiding this comment.
Looks good, thanks for all the work!
3 participants
Pre-submission checklist
Summary of Changes
Un-orphans the existing draft Glossary and populates it with definitions and resource links. The focus is on providing definitions for Charmed HPC charms in order to address #90. This includes the Slurm charms, Apptainer,
filesystem-client, InfluxDB, and SSSD. Charms not maintained by the Charmed HPC team are not directly defined but references are provided, e.g. the COS charms are not defined but COS itself is and the documentation linked to.The documentation tests currently fail due to the known issue of spellcheck applying to code/command blocks.
Related Issues, PRs, and Discussions
Closes #90