feat(docs): Evolve and standardize the documentation workflow

.github/workflows/docs.yaml

@@ -0,0 +1,12 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+
+jobs:
+  docs-checks:
+    uses: canonical/operator-workflows/.github/workflows/docs.yaml@main
+    secrets: inherit
+

.github/workflows/test.yaml

@@ -8,5 +8,5 @@ jobs:
     uses: canonical/operator-workflows/.github/workflows/test.yaml@main
     secrets: inherit
     with:
-      vale-style-check: true
+      vale-style-check: false
       with-uv: true

.gitignore

@@ -10,3 +10,16 @@ __pycache__/
 *.rock
 .venv/
 .vscode/
+
+# BEGIN VALE WORKFLOW IGNORE
+.vale/styles/*
+!.vale/styles/local
+!.vale/styles/config/
+
+.vale/styles/config/*
+!.vale/styles/config/vocabularies/
+
+.vale/styles/config/vocabularies/*
+!.vale/styles/config/vocabularies/local
+# END VALE WORKFLOW IGNORE
+

.vale.ini

@@ -0,0 +1,12 @@
+; Copyright 2025 Canonical Ltd.
+; See LICENSE file for licensing details.
+
+StylesPath = .vale/styles
+
+Packages = https://github.com/canonical/platform-engineering-vale-package/releases/download/latest/pfe-vale.zip
+
+Vocab = PFE, local
+
+[*]
+BasedOnStyles = PFE
+

CONTRIBUTING.md

@@ -6,7 +6,7 @@ This document explains the processes and practices recommended for contributing
 
 - Generally, before developing enhancements to this charm, you should consider [opening an issue](https://github.com/canonical/pollen-operator/issues) explaining your use case.
 - If you would like to chat with us about your use-cases or proposed implementation, you can reach
-  us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev)
+  us at the [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
   or [Discourse](https://discourse.charmhub.io/).
 - Familiarizing yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library
   will help you a lot when working on new features or bug fixes.
@@ -19,7 +19,7 @@ This document explains the processes and practices recommended for contributing
 
 ## Developing
 
-To make contributions to this charm, you'll need a working [development setup](https://juju.is/docs/sdk/dev-setup).
+To make contributions to this charm, you'll need a working [development setup](https://documentation.ubuntu.com/juju/3.6/howto/manage-your-deployment/).
 
 The code for this charm can be downloaded as follows:
 

Makefile

@@ -0,0 +1,41 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+# Top-level Makefile
+# Delegates targets to Makefile.docs
+
+# ==============================================================================
+# Macros
+# ==============================================================================
+
+# Colors
+NO_COLOR=\033[0m
+CYAN_COLOR=\033[0;36m
+YELLOW_COLOR=\033[0;93m
+RED_COLOR=\033[0;91m
+
+msg = @printf '$(CYAN_COLOR)$(1)$(NO_COLOR)\n'
+errmsg = @printf '$(RED_COLOR)Error: $(1)$(NO_COLOR)\n' && exit 1
+
+# ==============================================================================
+# Core
+# ==============================================================================
+
+include Makefile.docs
+
+.PHONY: help 
+help: _list-targets ## Prints all available targets
+
+.PHONY: _list-targets
+_list-targets: ## This collects and prints all targets, ignore internal commands
+	$(call msg,Available targets:)
+	@awk -F'[:#]' '                                               \
+		/^[a-zA-Z0-9._-]+:([^=]|$$)/ {                            \
+			target = $$1;                                         \
+			comment = "";                                         \
+			if (match($$0, /## .*/))                              \
+				comment = substr($$0, RSTART + 3);                \
+			if (target != ".PHONY" && target !~ /^_/ && !seen[target]++) \
+				printf "  make %-20s $(YELLOW_COLOR)# %s$(NO_COLOR)\n", target, comment;    \
+		}' $(MAKEFILE_LIST) | sort
+

Makefile.docs

@@ -0,0 +1,75 @@
+# Copyright 2025 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+# Minimal makefile for documentation
+#
+
+# Vale settings
+VALE_DIR ?= .vale
+PRAECEPTA_CONFIG 	?= .vale.ini
+DOCS_FILES 	?= docs/ README.md CONTRIBUTING.md
+
+HAS_VALE			:= $(shell command -v vale;)
+HAS_LYCHEE			:= $(shell command -v lychee;)
+
+# ==============================================================================
+# Docs Targets
+# ==============================================================================
+
+.PHONY: docs-check
+docs-check: vale lychee ## Run all Docs checks
+
+.PHONY: docs-clean
+docs-clean: vale-clean
+
+# ==============================================================================
+# Dependency Check Targets
+# ==============================================================================
+
+.PHONY: .check-vale
+.check-vale:
+ifndef HAS_VALE
+	$(call errmsg,'vale' is not installed. Please install it first) \
+	exit 1;
+endif
+
+.PHONY: .check-lychee
+.check-lychee:
+ifndef HAS_LYCHEE
+	$(call errmsg,'lychee' is not installed. Please install it first) \
+	exit 1;
+endif
+
+
+# ==============================================================================
+# Main Vale Targets
+# ==============================================================================
+
+.PHONY: vale-sync
+vale-sync: ## Download and install external Vale configuration sources
+	$(call msg,--- Syncing Vale styles... ---)
+	@vale sync
+
+.PHONY: vale
+vale: .check-vale vale-sync ## Run Vale checks on docs
+	$(call msg,--- Running Vale checks on "$(DOCS_FILES)"... ---)
+	@vale --config=$(PRAECEPTA_CONFIG) $(DOCS_FILES)
+
+# ==============================================================================
+# Main Lychee Targets
+# ==============================================================================
+
+.PHONY: lychee
+lychee: .check-lychee ## Run Lychee checks on docs
+	$(call msg,--- Running lychee checks on "$(LYCHEE_DOCS_FILES)"... ---)
+	@lychee $(DOCS_FILES)
+
+# ==============================================================================
+# Helper Targets
+# ==============================================================================
+
+.PHONY: vale-clean
+vale-clean:
+	$(call msg,--- Cleaning downloaded packages and ignored files from "$(VALE_DIR)"... ---)
+	@git clean -dfX $(VALE_DIR)
+

docs/explanation/charm-architecture.md

@@ -4,7 +4,7 @@
 
 This charm does not use an OCI image, as it runs directly on a machine rather than in a container. The charm uses the [pollen](https://github.com/canonical/pollen/blob/main/snap/snapcraft.yaml) [snap](https://ubuntu.com/core/docs/snaps-in-ubuntu-core) to install Pollen during deployment.
 
-Canonical provides a Pollen server as a service to the Ubuntu community at [https://entropy.ubuntu.com](https://entropy.ubuntu.com).
+Canonical provides a Pollen server as a service to the Ubuntu community at `https://entropy.ubuntu.com`.
 
 ## Metrics
 

docs/reference/external-access.md

@@ -1,4 +1,4 @@
 ## External access
 
 In order for the [Pollen](https://charmhub.io/pollen) charm to work correctly,
-it needs access to the [Snap Store's API](api.snapcraft.io) to download Pollen's snap.
+it needs access to the [Snap Store's API](https://api.snapcraft.io/) to download Pollen's snap.