docs: Update github-runner-operator to Mature home page milestone#801
docs: Update github-runner-operator to Mature home page milestone#801yanksyoon wants to merge 6 commits into
Conversation
yanksyoon
requested review from
cbartz,
florentianayuwono,
javierdelapuente,
weiiwang01 and
yhaliaw
as code owners
erinecon
left a comment
erinecon
left a comment
There was a problem hiding this comment.
Thank you so much for working on the home page 🎉 the great news for us is that we have a lot of pages and content to work with :D but this also means that the review will likely take a few rounds as I'll dig into the docs in greater detail. Thanks in advance for your patience!
I've limited this first round (mostly) to suggesting pages and categories for the table
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | | ||
| | Design | [Charm architecture](reference/charm-architecture.md) | [Security](explanation/security.md) | | ||
| | Security | [Cryptographic overview](reference/cryptographic-overview.md) | [Token scopes](reference/token-scopes.md) | [External Access](reference/external-access.md) | |
There was a problem hiding this comment.
The first thing I notice in the table's rendered output is that using the vertical lines | to separate the individual pages are causing issues in the table. So I think we should convert this to be {list-table} (see e.g. the HAProxy home page). It won't render nicely until we set up an RTD project though. So we could also use • as separators instead.
| |--|--| | ||
| | [Overview](https://charmhub.io/github-runner)</br> Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks | | ||
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | |
There was a problem hiding this comment.
Two comments here:
- Quick start should come first in the list
- "Managing resource usage" does not feel like a tutorial to me. It's not end-to-end, there are no commands for users to run, etc. If the content is still correct and relevant, I think we should move this document into the Explanation section.
| | [Overview](https://charmhub.io/github-runner)</br> Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks | | ||
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | |
There was a problem hiding this comment.
Other ideas for pages that we could include here: Change repository or organization, Change GitHub authentication
I also think that Configure runner storage might be a better fit in this row.
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | |
There was a problem hiding this comment.
Other ideas for pages that we could include here: Add custom labels, Set base image, Troubleshoot
But if you think any of these pages fall more into "Deployment" (meaning Day 0/1 operations), please let me know!
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | |
There was a problem hiding this comment.
Two comments here:
- "Product-specific feature" is a placeholder term -- we should update to something specific to the GH runner charm.
- I'm not sure what the product-specific feature you're trying to highlight with these pages. Maybe we should highlight the local-lxd track? Or perhaps the fact that LXD and OpenStack are both options? (I don't really know what "category" the LXD/OpenStack difference highlights -- maybe "runner types"? Let me know)
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | | ||
| | Design | [Charm architecture](reference/charm-architecture.md) | [Security](explanation/security.md) | |
There was a problem hiding this comment.
I think the Security page should go into the dedicated row
I also think we could add the ARM64 explanation page and maybe the Integrations page
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | | ||
| | Design | [Charm architecture](reference/charm-architecture.md) | [Security](explanation/security.md) | | ||
| | Security | [Cryptographic overview](reference/cryptographic-overview.md) | [Token scopes](reference/token-scopes.md) | [External Access](reference/external-access.md) | |
There was a problem hiding this comment.
Other pages we could add to the Security row: Security overview, Comply with security requirements, Manage external contributors
| * **How-to guides** — step-by-step guides covering key operations and common tasks. | ||
| * **Reference** — technical information such as specifications, APIs, and configuration options. | ||
| * **Explanation** — background, concepts, and design discussion. | ||
| * **Release notes** — summaries of changes and upgrade notes. |
There was a problem hiding this comment.
Since there are no release notes for the charm, I don't think we need to include it in this list
| ### Releases | ||
|
|
||
| * [Changelog](changelog.md) |
There was a problem hiding this comment.
this might be a little misleading since the changelog isn't really capturing releases -- I think we should remove
- Reorder Get started row with Quick start first - Move Managing resource usage from Tutorial to Explanation - Enhance Deployment row with Change repository/authentication pages - Add LXD runners row with custom labels, base image, troubleshoot - Rename 'Product-specific feature' to 'LXD runners' - Enhance Design row with Integrations and ARM64 pages - Expand Security row with all suggested security-related pages - Use bullet separators instead of pipes for better rendering - Remove Release notes from documentation organization section - Remove Changelog from Contents list - Move Managing resource usage and Security to Explanation section Addresses all comments from erinecon on PR #801
- Reorder Get started row with Quick start first - Move Managing resource usage from Tutorial to Explanation - Enhance Deployment row with Change repository/authentication pages - Add LXD runners row with custom labels, base image, troubleshoot - Rename 'Product-specific feature' to 'LXD runners' - Enhance Design row with Integrations and ARM64 pages - Expand Security row with all suggested security-related pages - Use bullet separators instead of pipes for better rendering - Remove Release notes from documentation organization section - Remove Changelog from Contents list - Move Managing resource usage and Security to Explanation section Addresses all comments from erinecon on PR #801
yanksyoon
force-pushed
the
docs/mature-home-milestone-isd-5894
branch
from
837b789 to
35caa5f
Compare
erinecon
left a comment
erinecon
left a comment
There was a problem hiding this comment.
Some general questions (which would probably lead to follow-up issues or PRs) and a nit
| |--|--| | ||
| | [Overview](https://charmhub.io/github-runner)</br> Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks | | ||
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Quick start](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | |
There was a problem hiding this comment.
| | Get started | [Quick start](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | | |
| | Get started | [Deploy the GitHub runner charm](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | |
Nit, "quick start" is ambiguous about what the user will do
| | Get started | [Quick start](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | | ||
| | Deployment | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) • [Change repository or organization](how-to/change-path.md) • [Change GitHub authentication](how-to/change-token.md) | | ||
| | Operations | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) • [Integrate with COS](how-to/integrate-with-cos.md) • [Debug with SSH](how-to/debug-with-ssh.md) • [Upgrade](how-to/upgrade.md) | | ||
| | LXD runners | [Add custom labels](local-lxd/how-to/add-custom-labels.md) • [Set base image](local-lxd/how-to/set-base-image.md) | |
There was a problem hiding this comment.
Question: Is there any documentation (reference or explanation) about the LXD runners, or the difference between LXD and OpenStack runners? I took a look through the documentation but didn't find anything.
Do you think it would benefit users to have this kind of document? (In a follow-up PR)
| 1. [SSH Debug](explanation/ssh-debug.md) | ||
| 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | ||
| 1. [Security](explanation/security.md) | ||
| 1. [Track local-lxd](local-lxd) |
There was a problem hiding this comment.
Some general questions about the local-lxd track:
- Is the long-term plan for this charm to support both LXD and OpenStack runners? If we're planning to drop support for one of the tracks, what would be the approximate time scale?
- Do you think it would benefit readers if the local-lxd documentation had a landing page? (Meaning
docs/local-lxd/index.md.) I think it might be good to have some formal introduction to this portion of the documentation.
yhaliaw
left a comment
yhaliaw
left a comment
There was a problem hiding this comment.
This PR restructures docs/index.md with a navigation grid, a Diátaxis orientation section, reorganized community links, and normalized TOC indentation with relative link targets — a solid documentation improvement. All link targets check out and the writing is clean; the inline comments flag two small label-consistency and categorization issues.
One out-of-diff note: the prose pointer explaining the local-lxd variant ("If you want to use ephemeral LXD virtual machines…") was removed in favor of the navigation grid. Consider adding a brief one-liner above or near the grid to preserve that discoverability for readers who arrive at the page without prior context (docs/index.md, around the former line 30 area).
🤝 Human review with AI assistance.
| 1. [SSH Debug](explanation/ssh-debug.md) | ||
| 1. [Changelog](changelog.md) | ||
| 1. [SSH Debug](explanation/ssh-debug.md) | ||
| 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) |
There was a problem hiding this comment.
local-lxd/tutorial/managing-resource-usage.md is listed under the top-level Explanation section of the Contents TOC, but its path places it in a tutorial/ directory, and every other local-lxd/* entry appears under the "Track local-lxd" section further down. The Diátaxis orientation section added in this same PR explicitly distinguishes Tutorials from Explanation, so this placement sits at odds with both the file's path and the model just described.
Either move this entry under "Track local-lxd" → Explanation (alongside the other local-lxd content) so path and category agree, or relocate the source file out of local-lxd/tutorial/ if classifying it as general explanation is the intent.
🤖 AI-assisted
|
|
||
| This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/): | ||
|
|
||
| * **Tutorials** — hands-on introductions for newcomers. |
There was a problem hiding this comment.
The Diátaxis orientation section lists "Tutorials — hands-on introductions for newcomers" as one of four categories, but the main (OpenStack) Contents TOC has no top-level Tutorial section — tutorials currently live only under "Track local-lxd". A newcomer reading this description may look for a main Tutorial section that isn't there.
Consider adding a brief parenthetical noting that hands-on tutorials currently live under the local-lxd track, or surfacing a top-level entry (e.g., a Quick start) in the main TOC to fulfil the expectation the description sets.
🤖 AI-assisted
3 participants
What this PR does
Update to latest home page milestone
Why we need it
Documentation quality sync
Checklist
docs/changelog.mdwith user-relevant changesterraform fmtpasses andtflintreports no errorsgithub-runner-manager/pyproject.toml.Only documentation change.