Skip to content

Move multi-node tutorial to how-to section#427

Merged
sabaini merged 4 commits intocanonical:mainfrom
skoech:multi-node_tutorial_how-to
Oct 8, 2024
Merged

Move multi-node tutorial to how-to section#427
sabaini merged 4 commits intocanonical:mainfrom
skoech:multi-node_tutorial_how-to

Conversation

@skoech
Copy link
Copy Markdown
Collaborator

@skoech skoech commented Sep 24, 2024

Description

The guide to installing MicroCeph on multiple machines is currently presented as a tutorial although it is more appropriate as a how-to guide. This change moves it to the how-to guides section of the documentation.

Type of change

  • Documentation update (Doc only change)

@skoech skoech added the documentation Improvements or additions to documentation label Sep 24, 2024
@skoech skoech requested review from lmlg and sabaini September 24, 2024 13:10
@UtkarshBhatthere UtkarshBhatthere self-requested a review September 25, 2024 12:03
@skoech skoech requested review from UtkarshBhatthere and removed request for UtkarshBhatthere September 25, 2024 12:03
Copy link
Copy Markdown
Collaborator

@sabaini sabaini left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs a TOC update as well

skoech added 2 commits October 3, 2024 14:40
Signed-off-by: Sharon Koech <sharon.koech@canonical.com>
Signed-off-by: Sharon Koech <sharon.koech@canonical.com>
@skoech skoech force-pushed the multi-node_tutorial_how-to branch from 2e3266f to bffeab6 Compare October 3, 2024 12:19
skoech added 2 commits October 3, 2024 15:25
Signed-off-by: Sharon Koech <sharon.koech@canonical.com>
Signed-off-by: Sharon Koech <sharon.koech@canonical.com>
@skoech skoech requested a review from sabaini October 3, 2024 12:48
@UtkarshBhatthere
Copy link
Copy Markdown
Contributor

Hey, was just wondering if the multi node documentation does not qualify to be a tutorial ?

@skoech
Copy link
Copy Markdown
Collaborator Author

skoech commented Oct 4, 2024

Hey @UtkarshBhatthere! After testing the multi-node tutorial, I thought it didn't qualify to be a tutorial either because it didn’t feel like a learning experience. Rather, I was able to get something done (deploy a multi-node cluster), which is great, but it didn't teach me any MicroCeph concepts e.g. nodes, clusters, why they are useful or even which basic hardware requirements I needed to perform the deployment. It assumed lots of prior knowledge on my part, something an entry-level tutorial shouldn't do.

We need an end-to-end tutorial suitable for new users. I suggested repurposing the previous single-node tutorial because at the end of it, the user will have achieved a simple yet meaningful task (it's also memorable since it takes only 3 commands to set it up) but in order to make it end-to-end, we need to add a prerequisites section at the beginning and a clean-up section at the end. Also, it would be nice to teach the user ways in which they can interact with their new cluster e.g. check health, enable radosgw, and consume their cluster storage e.g. host a static website.

And then, after giving the user this basic introduction, we can now show them HOW TO do the same thing but with multiple nodes. What do you think about this approach?

@sabaini
Copy link
Copy Markdown
Collaborator

sabaini commented Oct 8, 2024

thanks, lgtm!

@sabaini sabaini merged commit 4c28584 into canonical:main Oct 8, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants