feat(docs): Evolve and standardize the documentation workflow

[erinecon]

Description:

This PR builds upon our team's commitment to high-quality documentation by formalizing and standardizing our style-checking workflow.

It evolves our existing efforts of checking against the Canonical Documentation Style Guide (praecepta) into a fully integrated, vale-native process. This more streamlined approach unlocks powerful new capabilities for the team, including:

• Seamless integration with the official Vale GitHub Action for automated checks via a new docs workflow
• Simple and consistent make targets for reliable local validation, in line with CI validation.
• The ability to use IDE extensions for real-time feedback while writing.

---

Key Changes

• CI Automation:

  • Leveraging our new docs workflow to run on every pull request to:
    • Lint all documentation using Vale.
    • Check for broken links.

• Layered Vale Configuration:

  • Project-Level: A local .vale.ini and accept.txt allow for project-specific vocabulary and rule overrides.
  • Team-Level: The configuration inherits from our new central platform-engineering-vale package, allowing us to manage team-wide vocabulary and rules in one place.
  • Company-Level: The team package is configured to enherit the official Canonical Documentation Style Guide (praecepta), ensuring we stay aligned with broader company standards.

• Improved Local Experience:

  • A new Makefile and Makefile.docs provide simple targets for authors to validate their work locally before pushing.
  • Running make vale, make lychee or make docs-check locally is now identical to the checks run in CI, eliminating surprises.

Interested in adding this workflow to a project?

You can add this entire standardized workflow to your own repository with a single command.

First, ensure you are in the root of your project on a new branch (not main), then run:

bash <(curl -sSL "https://raw.githubusercontent.com/srbouffard/vale-workflow-template/main/bootstrap.sh?$(date +%s)")

The script is interactive and will guide you through the setup.

Juju events changes

None

Module changes

None

Library changes

None

Checklist

• The charm style guide was applied
• The contributing guide was applied
• The changes are compliant with ISD054 - Manging Charm Complexity
• The documentation for charmhub is updated.
• The PR is tagged with appropriate label (urgent, trivial, complex)

Either discourse-gatekeeper will update the documentation, or I will upon the approval of this PR.