Skip to content

Clarify service entry points and remove documentation dead ends#121

Open
YunaBraska wants to merge 1 commit into
safespring:masterfrom
YunaBraska:clarify-service-entry-points
Open

Clarify service entry points and remove documentation dead ends#121
YunaBraska wants to merge 1 commit into
safespring:masterfrom
YunaBraska:clarify-service-entry-points

Conversation

@YunaBraska

Copy link
Copy Markdown

What changed

  • Reworked the homepage around audience, product choice, access, first tasks, and service availability.
  • Gave service entry points product-specific titles and made the real SKE cluster walkthrough the first SKE task.
  • Replaced the unfinished Portal/API page with an honest router to service-specific portal, API, and automation documentation.
  • Rebuilt the Backup and Storage entry pages around explicit prerequisites, terminology, outcomes, and continuation paths.
  • Removed placeholder-only compliance pages and unpublished placeholder subsections from navigation and search.
  • Improved support guidance and fixed broken internal links, anchors, and the Backup rekey navigation path.
  • Configured the canonical site URL so the generated sitemap contains valid documentation URLs.

Why

The documentation assumed product and account context that first-time readers do not have. Several primary-navigation pages were unfinished future-tense outlines, while generic page titles and conflicting entry paths made it difficult to identify the correct service or first task.

This change makes the public entry points describe what the site documents and routes readers only to guidance that currently exists.

User impact

  • New readers can identify each documented service and reach a real first task from the homepage.
  • Backup, Storage, SKE, and portal users see prerequisites and expected outcomes before following operational steps.
  • Placeholder-only pages no longer appear as finished documentation.
  • Support requests receive clearer diagnostic context without asking customers to email secrets.

How to test

  • docker run --rm -v "$PWD:/docs:ro" squidfunk/mkdocs-material:4.3.1 build --strict --site-dir /tmp/site
  • pyspelling
  • Recursive local-site crawl with wget --spider: no broken links.
  • Generated sitemap validation: 152 canonical URLs, zero None entries.
  • Generated HTML anchor comparison: no new broken anchors relative to master.
  • git diff --check

Notes

The removed files contained only placeholder content. Their old direct URLs are intentionally no longer published; no internal links target them.

@YunaBraska
YunaBraska marked this pull request as ready for review July 16, 2026 05:51

@mrjson79 mrjson79 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

approved.

@oquinena oquinena left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good! Approved

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants