Skip to content

docs: update how-to and reference landing pages#93

Merged
florentianayuwono merged 6 commits into
mainfrom
docs/update-how-to-reference-landing-pages-isd-5859
May 27, 2026
Merged

docs: update how-to and reference landing pages#93
florentianayuwono merged 6 commits into
mainfrom
docs/update-how-to-reference-landing-pages-isd-5859

Conversation

@florentianayuwono
Copy link
Copy Markdown
Collaborator

What this PR does

Updates the how-to and reference landing pages to improve documentation quality.

  • Removes meta-descriptions from all sections (phrases like "The following guides cover...", "This section contains...", etc.)
  • Merges the orphan "Development" section (single page) into "Update and refresh", renaming the combined section "Maintenance and development"
  • Merges the orphan "Architecture and deployments" section (single page) into a new "Configuration and operations" section in the reference index
  • Adds visible bullet-list links to each section for easier navigation
  • Adds meaningful, subject-focused section descriptions that explain context rather than describing the documentation itself

Why we need it

Meta-descriptions add noise without value — readers can see what pages are listed. Orphan sections (single page under a heading) fragment the navigation unnecessarily. These changes follow the documentation standards demonstrated in the wordpress-k8s-operator docs.

Checklist

  • I followed the contributing guide
  • I added or updated the documentation (if applicable)
  • I updated docs/changelog.md with user-relevant changes
  • I used AI to assist with preparing this PR
  • I added or updated tests as needed (unit and integration)
  • If integration test modules are used: I updated the workflow configuration
    (e.g., in .github/workflows/integration_tests.yaml, ensure the modules list is correct)
  • If this is a Grafana dashboard: I added a screenshot of the dashboard
  • If this is Terraform: terraform fmt passes and tflint reports no errors
  • If this is Rockcraft: I updated the version

Test plan

Documentation-only change. Verified by reviewing the rendered RST structure: toctree entries are preserved, bullet links are correct, and no orphan sections remain.

Review focus

  • Section groupings and naming: does "Maintenance and development" feel right for back-up-restore + upgrade + contribute?
  • Section groupings in reference: does "Configuration and operations" (actions, configurations, charm-architecture) + "Connectivity and monitoring" (integrations, metrics) make sense?
  • Section descriptions: are they meaningful without being meta?

- Remove meta-descriptions from all sections
- Merge orphan 'Development' section into 'Maintenance and development'
- Merge orphan 'Architecture and deployments' into 'Configuration and
  operations' in reference
- Add visible bullet-list links and meaningful section descriptions

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@florentianayuwono florentianayuwono requested a review from a team as a code owner May 26, 2026 13:53
@florentianayuwono florentianayuwono self-assigned this May 26, 2026
@florentianayuwono florentianayuwono added the documentation Improvements or additions to documentation label May 26, 2026
@florentianayuwono florentianayuwono requested a review from Copilot May 26, 2026 13:56
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

This PR updates the documentation landing pages for How-to and Reference to improve information scent and reduce meta/boilerplate descriptions, while regrouping pages into more cohesive sections.

Changes:

  • Rewrites landing-page intro and section descriptions to be more subject-focused (less “this section contains…”).
  • Restructures section groupings in both how-to and reference indexes (merging previously orphaned single-page sections).
  • Reorders which pages appear under each heading (e.g., moving Charm architecture under “Configuration and operations”).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File Description
docs/reference/index.rst Reworks reference landing-page text and reorganizes pages into “Configuration and operations” and “Connectivity and monitoring”.
docs/how-to/index.rst Rewords how-to landing page and merges “Development” into “Maintenance and development”.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/reference/index.rst
Comment thread docs/reference/index.rst Outdated
Comment thread docs/how-to/index.rst
Comment thread docs/how-to/index.rst Outdated
Comment thread docs/reference/index.rst Outdated
Comment thread docs/how-to/index.rst
Copy link
Copy Markdown
Contributor

@erinecon erinecon left a comment

Choose a reason for hiding this comment

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

Thanks so much for implementing Daniele's feedback into the landing pages! I agree with all of Copilot's suggestions, and I added a nit + question for some potential follow-up work

Comment thread docs/how-to/index.rst
Comment thread docs/how-to/index.rst Outdated
Comment thread docs/reference/index.rst Outdated
Comment thread docs/reference/index.rst Outdated
Comment thread docs/reference/index.rst Outdated
florentianayuwono and others added 5 commits May 26, 2026 21:49
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Erin Conley <erin.conley@canonical.com>
@florentianayuwono florentianayuwono enabled auto-merge (squash) May 27, 2026 03:22
@florentianayuwono florentianayuwono merged commit 2deb2dc into main May 27, 2026
31 checks passed
@florentianayuwono florentianayuwono deleted the docs/update-how-to-reference-landing-pages-isd-5859 branch May 27, 2026 03:42
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 Libraries: OK

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants