canonical / canonical/microceph
Add brief context to the bootstrap action in the tutorial
- Dominant language
- Go
- Stars
- 396
- Forks
- 74
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 7
Description
## Background
In the [MicroCeph tutorial](https://documentation.ubuntu.com/microceph/latest/), we guide a user through deploying a Ceph cluster and consuming object storage. _Bootstrapping_ the cluster is a fundamental step, but it is quite vague: _"..bootstrap your new Ceph storage cluster."_ doesn't say anything about what this means. While the term "bootstrap" is a common industry term, it may be foreign to new users. Replacing it with a simpler term may not be effective, but shedding some light on its meaning and significance would create a better learning experience for our new users. It would be useful to make the user understand what cluster bootstrap is, and what it does.
## Prerequisites
This is an ideal task for a new contributor who is interested in learning about Ceph, and how to write good documentation. Prior knowledge of Git, Sphinx and rST is not required; this is an opportunity to learn all these. Prior knowledge of cloud storage is a good-to-have, but not necessary.
## Learnings
Upon completion of this task, you will have learned/gained the following:
- Writing a good tutorial, using the [Diátaxis](https://diataxis.fr/) framework
- User focus in documentation
- A basic understanding of how MicroCeph (and Ceph) works
- Working with the GitHub pull request workflow
## Task
Add brief context about the bootstrap action in the [_Initialise your cluster_](https://documentation.ubuntu.com/microceph/latest/snap/tutorial/get-started/#initialise-your-cluster) section of the tutorial
> [! IMPORTANT]:
> If it’s your first time contributing to a Canonical project, you will need to sign the [Canonical Contributor Licence Agreement](https://ubuntu.com/legal/contributors) (CLA). Read more about why in our [contributor guide](https://documentation.ubuntu.com/microceph/stable/contributing/#the-cla-check).
### Scope
Since this is a tutorial, the description should be brief and accessible. Do not overwhelm the user with overly complex background details.
## Outcome
The additional context provided for the bootstrap will improve the learning experience for our new users and increase their confidence in their next steps, and why they are making them.
## Resources
- [MicroCeph Tutorial](https://canonical-microceph.readthedocs-hosted.com/latest/tutorial/get-started/#initialise-your-cluster)
- [Information about cluster bootstrap in upstream Ceph documentation](https://docs.ceph.com/en/latest/cephadm/install/#what-to-know-before-you-bootstrap)
- [Diátaxis](https://diataxis.fr/)
- [MicroCeph documentation contributor guide](https://documentation.ubuntu.com/microceph/stable/contributing/)
- Check out the [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
- If you are new to CODA, learn about the community in the [CODA website](https://documentation.academy/).
## Mentor
The mentor for this issue is @skoech. They are the technical author for [Ceph](https://canonical.com/ceph).
Thank you in advance for your contribution!
Contributor guide
Research direction
Start with the “Initialise your cluster” section of the MicroCeph tutorial and read the linked upstream Ceph bootstrap guidance for context. Add a brief, accessible explanation of what bootstrapping does and why it matters, then review the rendered tutorial to confirm the explanation is concise and clear for new users.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 90/100