Skip to content

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

Closed
florentianayuwono wants to merge 1 commit into
mainfrom
docs/update-how-to-reference-landing-pages
Closed

docs: update how-to and reference landing pages#92
florentianayuwono wants to merge 1 commit into
mainfrom
docs/update-how-to-reference-landing-pages

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:48
@florentianayuwono florentianayuwono self-assigned this May 26, 2026
@florentianayuwono florentianayuwono added the documentation Improvements or additions to documentation label May 26, 2026
@florentianayuwono florentianayuwono deleted the docs/update-how-to-reference-landing-pages branch May 26, 2026 13:52
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.

1 participant