grafana / writers-toolkit

Technical documentation guidelines for Grafana Labs documentation
https://grafana.com/docs/writers-toolkit/
16 stars 12 forks source link

Add creation date to all pages #754

Closed jdbaldry closed 2 weeks ago

jdbaldry commented 2 weeks ago

By convention, the Hugo date front matter usually represents creation date: https://gohugo.io/content-management/front-matter/#date.

Having this date lets me configure an RSS feed for Writers' Toolkit that readers can subscribe to and receive updates for new pages.

Signed-off-by: Jack Baldry jack.baldry@grafana.com

github-actions[bot] commented 2 weeks ago

Readability report

File AutomatedReadability ColemanLiau FleschKincaid FleschReadingEase GunningFog LIX SMOG
docs/sources/_index.md $${9.83\space\color{black}(Δ+0.00)}$$ $${11.46\space\color{black}(Δ+0.00)}$$ $${9.18\space\color{black}(Δ+0.00)}$$ $${57.49\space\color{black}(Δ+0.00)}$$ $${11.07\space\color{black}(Δ+0.00)}$$ $${45.01\space\color{black}(Δ+0.00)}$$ $${10.95\space\color{black}(Δ+0.00)}$$
docs/sources/contribute/_index.md $${7.56\space\color{black}(Δ+0.00)}$$ $${10.37\space\color{black}(Δ+0.00)}$$ $${8.47\space\color{black}(Δ+0.00)}$$ $${56.00\space\color{black}(Δ+0.00)}$$ $${9.60\space\color{black}(Δ+0.00)}$$ $${38.59\space\color{black}(Δ+0.00)}$$ $${10.47\space\color{black}(Δ+0.00)}$$
docs/sources/contribute/release-notes/index.md $${8.30\space\color{black}(Δ+0.00)}$$ $${9.37\space\color{black}(Δ+0.00)}$$ $${8.78\space\color{black}(Δ+0.00)}$$ $${60.98\space\color{black}(Δ+0.00)}$$ $${10.60\space\color{black}(Δ+0.00)}$$ $${37.78\space\color{black}(Δ+0.00)}$$ $${11.34\space\color{black}(Δ+0.00)}$$
docs/sources/get-started/_index.md $${7.10\space\color{black}(Δ+0.00)}$$ $${11.06\space\color{black}(Δ+0.00)}$$ $${7.91\space\color{black}(Δ+0.00)}$$ $${53.23\space\color{black}(Δ+0.00)}$$ $${9.73\space\color{black}(Δ+0.00)}$$ $${37.34\space\color{black}(Δ+0.00)}$$ $${9.99\space\color{black}(Δ+0.00)}$$
docs/sources/introduction/index.md $${8.99\space\color{black}(Δ+0.00)}$$ $${13.34\space\color{black}(Δ+0.00)}$$ $${9.96\space\color{black}(Δ+0.00)}$$ $${39.19\space\color{black}(Δ+0.00)}$$ $${11.68\space\color{black}(Δ+0.00)}$$ $${45.60\space\color{black}(Δ+0.00)}$$ $${11.35\space\color{black}(Δ+0.00)}$$
docs/sources/review/_index.md $${5.24\space\color{black}(Δ+0.00)}$$ $${8.80\space\color{black}(Δ+0.00)}$$ $${4.49\space\color{black}(Δ+0.00)}$$ $${77.10\space\color{black}(Δ+0.00)}$$ $${4.45\space\color{black}(Δ+0.00)}$$ $${26.75\space\color{black}(Δ+0.00)}$$ $${5.99\space\color{black}(Δ+0.00)}$$
docs/sources/review/backport-changes/index.md $${11.86\space\color{black}(Δ+0.00)}$$ $${10.90\space\color{black}(Δ+0.00)}$$ $${11.66\space\color{black}(Δ+0.00)}$$ $${49.98\space\color{black}(Δ+0.00)}$$ $${13.23\space\color{black}(Δ+0.00)}$$ $${51.35\space\color{black}(Δ+0.00)}$$ $${13.26\space\color{black}(Δ+0.00)}$$
docs/sources/review/cla-assistant/index.md $${8.16\space\color{black}(Δ+0.00)}$$ $${10.72\space\color{black}(Δ+0.00)}$$ $${8.85\space\color{black}(Δ+0.00)}$$ $${54.87\space\color{black}(Δ+0.00)}$$ $${10.99\space\color{black}(Δ+0.00)}$$ $${41.44\space\color{black}(Δ+0.00)}$$ $${11.67\space\color{black}(Δ+0.00)}$$
docs/sources/review/doc-validator/_index.md $${8.40\space\color{black}(Δ+0.00)}$$ $${11.54\space\color{black}(Δ+0.00)}$$ $${9.83\space\color{black}(Δ+0.00)}$$ $${45.73\space\color{black}(Δ+0.00)}$$ $${11.34\space\color{black}(Δ+0.00)}$$ $${46.30\space\color{black}(Δ+0.00)}$$ $${11.96\space\color{black}(Δ+0.00)}$$
docs/sources/review/doc-validator/errata.md $${4.01\space\color{black}(Δ+0.00)}$$ $${7.35\space\color{black}(Δ+0.00)}$$ $${6.77\space\color{black}(Δ+0.00)}$$ $${59.31\space\color{black}(Δ+0.00)}$$ $${8.84\space\color{black}(Δ+0.00)}$$ $${30.69\space\color{black}(Δ+0.00)}$$ $${9.21\space\color{black}(Δ+0.00)}$$
docs/sources/review/lint-prose/_index.md $${5.62\space\color{black}(Δ+0.00)}$$ $${8.81\space\color{black}(Δ+0.00)}$$ $${7.04\space\color{black}(Δ+0.00)}$$ $${62.11\space\color{black}(Δ+0.00)}$$ $${9.60\space\color{black}(Δ+0.00)}$$ $${31.42\space\color{black}(Δ+0.00)}$$ $${10.29\space\color{black}(Δ+0.00)}$$
docs/sources/review/lint-prose/dictionary/_index.md $${6.94\space\color{black}(Δ+0.00)}$$ $${10.18\space\color{black}(Δ+0.00)}$$ $${8.93\space\color{black}(Δ+0.00)}$$ $${50.04\space\color{black}(Δ+0.00)}$$ $${10.36\space\color{black}(Δ+0.00)}$$ $${40.51\space\color{black}(Δ+0.00)}$$ $${11.21\space\color{black}(Δ+0.00)}$$
docs/sources/review/lint-prose/dictionary/add-words.md $${5.63\space\color{black}(Δ+0.00)}$$ $${9.23\space\color{black}(Δ+0.00)}$$ $${6.52\space\color{black}(Δ+0.00)}$$ $${63.14\space\color{black}(Δ+0.00)}$$ $${7.93\space\color{black}(Δ+0.00)}$$ $${35.10\space\color{black}(Δ+0.00)}$$ $${9.73\space\color{black}(Δ+0.00)}$$
docs/sources/review/test-documentation-changes/index.md $${7.01\space\color{black}(Δ+0.00)}$$ $${10.27\space\color{black}(Δ+0.00)}$$ $${8.61\space\color{black}(Δ+0.00)}$$ $${52.35\space\color{black}(Δ+0.00)}$$ $${10.56\space\color{black}(Δ+0.00)}$$ $${40.89\space\color{black}(Δ+0.00)}$$ $${11.21\space\color{black}(Δ+0.00)}$$
docs/sources/shared/hugo-error-example-bad-link.md $${8.97\space\color{black}(Δ+0.00)}$$ $${12.05\space\color{black}(Δ+0.00)}$$ $${10.48\space\color{black}(Δ+0.00)}$$ $${41.88\space\color{black}(Δ+0.00)}$$ $${14.66\space\color{black}(Δ+0.00)}$$ $${43.86\space\color{black}(Δ+0.00)}$$ $${13.90\space\color{black}(Δ+0.00)}$$
docs/sources/shared/make-help.md $${8.45\space\color{black}(Δ+0.00)}$$ $${11.60\space\color{black}(Δ+0.00)}$$ $${11.07\space\color{black}(Δ+0.00)}$$ $${36.81\space\color{black}(Δ+0.00)}$$ $${12.94\space\color{black}(Δ+0.00)}$$ $${43.18\space\color{black}(Δ+0.00)}$$ $${13.02\space\color{black}(Δ+0.00)}$$
docs/sources/shared/refs-example.md $${7.67\space\color{black}(Δ+0.00)}$$ $${10.41\space\color{black}(Δ+0.00)}$$ $${8.37\space\color{black}(Δ+0.00)}$$ $${57.12\space\color{black}(Δ+0.00)}$$ $${9.15\space\color{black}(Δ+0.00)}$$ $${39.82\space\color{black}(Δ+0.00)}$$ $${11.21\space\color{black}(Δ+0.00)}$$
docs/sources/structure/_index.md $${7.95\space\color{black}(Δ+0.00)}$$ $${10.32\space\color{black}(Δ+0.00)}$$ $${8.88\space\color{black}(Δ+0.00)}$$ $${55.18\space\color{black}(Δ+0.00)}$$ $${10.30\space\color{black}(Δ+0.00)}$$ $${36.82\space\color{black}(Δ+0.00)}$$ $${10.87\space\color{black}(Δ+0.00)}$$
docs/sources/structure/about-documentation-design/index.md $${10.24\space\color{black}(Δ+0.00)}$$ $${13.83\space\color{black}(Δ+0.00)}$$ $${11.49\space\color{black}(Δ+0.00)}$$ $${33.87\space\color{black}(Δ+0.00)}$$ $${12.05\space\color{black}(Δ+0.00)}$$ $${43.66\space\color{black}(Δ+0.00)}$$ $${12.26\space\color{black}(Δ+0.00)}$$
docs/sources/structure/topic-types/_index.md $${8.34\space\color{black}(Δ+0.00)}$$ $${11.41\space\color{black}(Δ+0.00)}$$ $${8.12\space\color{black}(Δ+0.00)}$$ $${58.19\space\color{black}(Δ+0.00)}$$ $${9.32\space\color{black}(Δ+0.00)}$$ $${41.76\space\color{black}(Δ+0.00)}$$ $${10.29\space\color{black}(Δ+0.00)}$$
docs/sources/structure/topic-types/concept/index.md $${7.26\space\color{black}(Δ+0.00)}$$ $${11.15\space\color{black}(Δ+0.00)}$$ $${7.85\space\color{black}(Δ+0.00)}$$ $${54.57\space\color{black}(Δ+0.00)}$$ $${8.58\space\color{black}(Δ+0.00)}$$ $${41.12\space\color{black}(Δ+0.00)}$$ $${9.89\space\color{black}(Δ+0.00)}$$
docs/sources/structure/topic-types/reference/index.md $${7.76\space\color{black}(Δ+0.00)}$$ $${11.47\space\color{black}(Δ+0.00)}$$ $${9.06\space\color{black}(Δ+0.00)}$$ $${47.68\space\color{black}(Δ+0.00)}$$ $${11.27\space\color{black}(Δ+0.00)}$$ $${38.68\space\color{black}(Δ+0.00)}$$ $${11.44\space\color{black}(Δ+0.00)}$$
docs/sources/structure/topic-types/task/index.md $${7.97\space\color{black}(Δ+0.00)}$$ $${10.71\space\color{black}(Δ+0.00)}$$ $${8.33\space\color{black}(Δ+0.00)}$$ $${57.71\space\color{black}(Δ+0.00)}$$ $${9.27\space\color{black}(Δ+0.00)}$$ $${37.19\space\color{black}(Δ+0.00)}$$ $${10.63\space\color{black}(Δ+0.00)}$$
docs/sources/structure/topic-types/tutorial/index.md $${7.99\space\color{black}(Δ+0.00)}$$ $${10.41\space\color{black}(Δ+0.00)}$$ $${9.55\space\color{black}(Δ+0.00)}$$ $${50.26\space\color{black}(Δ+0.00)}$$ $${11.63\space\color{black}(Δ+0.00)}$$ $${41.63\space\color{black}(Δ+0.00)}$$ $${11.95\space\color{black}(Δ+0.00)}$$
docs/sources/structure/topic-types/visualization/index.md $${7.30\space\color{black}(Δ+0.00)}$$ $${10.94\space\color{black}(Δ+0.00)}$$ $${9.72\space\color{black}(Δ+0.00)}$$ $${42.78\space\color{black}(Δ+0.00)}$$ $${9.90\space\color{black}(Δ+0.00)}$$ $${38.19\space\color{black}(Δ+0.00)}$$ $${10.74\space\color{black}(Δ+0.00)}$$
docs/sources/write/_index.md $${10.10\space\color{black}(Δ+0.00)}$$ $${13.22\space\color{black}(Δ+0.00)}$$ $${10.30\space\color{black}(Δ+0.00)}$$ $${44.22\space\color{black}(Δ+0.00)}$$ $${10.43\space\color{black}(Δ+0.00)}$$ $${48.56\space\color{black}(Δ+0.00)}$$ $${12.16\space\color{black}(Δ+0.00)}$$
docs/sources/write/deprecate-remove/index.md $${9.50\space\color{black}(Δ+0.00)}$$ $${11.82\space\color{black}(Δ+0.00)}$$ $${10.57\space\color{black}(Δ+0.00)}$$ $${44.71\space\color{black}(Δ+0.00)}$$ $${12.25\space\color{black}(Δ+0.00)}$$ $${45.88\space\color{black}(Δ+0.00)}$$ $${12.55\space\color{black}(Δ+0.00)}$$
docs/sources/write/front-matter/index.md $${6.85\space\color{black}(Δ+0.00)}$$ $${9.28\space\color{black}(Δ+0.00)}$$ $${8.00\space\color{black}(Δ+0.00)}$$ $${60.22\space\color{black}(Δ+0.00)}$$ $${10.07\space\color{black}(Δ+0.00)}$$ $${36.78\space\color{black}(Δ+0.00)}$$ $${11.08\space\color{black}(Δ+0.00)}$$
docs/sources/write/image-guidelines/index.md $${7.44\space\color{black}(Δ+0.00)}$$ $${10.89\space\color{black}(Δ+0.00)}$$ $${8.59\space\color{black}(Δ+0.00)}$$ $${52.06\space\color{black}(Δ+0.00)}$$ $${10.78\space\color{black}(Δ+0.00)}$$ $${37.88\space\color{black}(Δ+0.00)}$$ $${11.18\space\color{black}(Δ+0.00)}$$
docs/sources/write/links/_index.md $${5.47\space\color{black}(Δ+0.00)}$$ $${8.80\space\color{black}(Δ+0.00)}$$ $${6.80\space\color{black}(Δ+0.00)}$$ $${62.87\space\color{black}(Δ+0.00)}$$ $${8.62\space\color{black}(Δ+0.00)}$$ $${33.27\space\color{black}(Δ+0.00)}$$ $${9.85\space\color{black}(Δ+0.00)}$$
docs/sources/write/links/useful-link-text.md $${5.36\space\color{black}(Δ+0.00)}$$ $${7.51\space\color{black}(Δ+0.00)}$$ $${6.31\space\color{black}(Δ+0.00)}$$ $${71.95\space\color{black}(Δ+0.00)}$$ $${9.32\space\color{black}(Δ+0.00)}$$ $${32.32\space\color{black}(Δ+0.00)}$$ $${10.19\space\color{black}(Δ+0.00)}$$
docs/sources/write/markdown-guide/index.md $${6.78\space\color{black}(Δ+0.00)}$$ $${10.37\space\color{black}(Δ+0.00)}$$ $${7.28\space\color{black}(Δ+0.00)}$$ $${59.89\space\color{black}(Δ+0.00)}$$ $${8.69\space\color{black}(Δ+0.00)}$$ $${35.85\space\color{black}(Δ+0.00)}$$ $${10.13\space\color{black}(Δ+0.00)}$$
docs/sources/write/reuse-content/_index.md $${7.91\space\color{black}(Δ+0.00)}$$ $${11.20\space\color{black}(Δ+0.00)}$$ $${7.76\space\color{black}(Δ+0.00)}$$ $${59.38\space\color{black}(Δ+0.00)}$$ $${9.31\space\color{black}(Δ+0.00)}$$ $${41.38\space\color{black}(Δ+0.00)}$$ $${10.34\space\color{black}(Δ+0.00)}$$
docs/sources/write/reuse-content/reuse-directories/index.md $${6.86\space\color{black}(Δ+0.00)}$$ $${10.14\space\color{black}(Δ+0.00)}$$ $${9.02\space\color{black}(Δ+0.00)}$$ $${49.15\space\color{black}(Δ+0.00)}$$ $${11.81\space\color{black}(Δ+0.00)}$$ $${35.62\space\color{black}(Δ+0.00)}$$ $${11.68\space\color{black}(Δ+0.00)}$$
docs/sources/write/reuse-content/reuse-shared-content/index.md $${9.08\space\color{black}(Δ+0.00)}$$ $${11.11\space\color{black}(Δ+0.00)}$$ $${8.88\space\color{black}(Δ+0.00)}$$ $${57.52\space\color{black}(Δ+0.00)}$$ $${9.86\space\color{black}(Δ+0.00)}$$ $${44.85\space\color{black}(Δ+0.00)}$$ $${10.99\space\color{black}(Δ+0.00)}$$
docs/sources/write/shortcodes/index.md $${7.30\space\color{black}(Δ+0.00)}$$ $${10.36\space\color{black}(Δ+0.00)}$$ $${8.15\space\color{black}(Δ+0.00)}$$ $${56.90\space\color{black}(Δ+0.00)}$$ $${9.67\space\color{black}(Δ+0.00)}$$ $${39.34\space\color{black}(Δ+0.00)}$$ $${10.96\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/_index.md $${8.82\space\color{black}(Δ+0.00)}$$ $${12.09\space\color{black}(Δ+0.00)}$$ $${8.61\space\color{black}(Δ+0.00)}$$ $${54.34\space\color{black}(Δ+0.00)}$$ $${8.11\space\color{black}(Δ+0.00)}$$ $${42.31\space\color{black}(Δ+0.00)}$$ $${11.60\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/capitalization-punctuation/index.md $${8.73\space\color{black}(Δ+0.00)}$$ $${11.93\space\color{black}(Δ+0.00)}$$ $${9.27\space\color{black}(Δ+0.00)}$$ $${49.84\space\color{black}(Δ+0.00)}$$ $${10.64\space\color{black}(Δ+0.00)}$$ $${41.27\space\color{black}(Δ+0.00)}$$ $${12.03\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/inclusive-writing/index.md $${6.28\space\color{black}(Δ+0.00)}$$ $${9.57\space\color{black}(Δ+0.00)}$$ $${7.67\space\color{black}(Δ+0.00)}$$ $${58.02\space\color{black}(Δ+0.00)}$$ $${9.98\space\color{black}(Δ+0.00)}$$ $${37.36\space\color{black}(Δ+0.00)}$$ $${10.76\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/style-conventions/index.md $${7.47\space\color{black}(Δ+0.00)}$$ $${10.43\space\color{black}(Δ+0.00)}$$ $${8.29\space\color{black}(Δ+0.00)}$$ $${56.55\space\color{black}(Δ+0.00)}$$ $${10.23\space\color{black}(Δ+0.00)}$$ $${38.86\space\color{black}(Δ+0.00)}$$ $${11.19\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/ui-elements/index.md $${4.34\space\color{black}(Δ+0.00)}$$ $${6.81\space\color{black}(Δ+0.00)}$$ $${6.22\space\color{black}(Δ+0.00)}$$ $${70.05\space\color{black}(Δ+0.00)}$$ $${6.82\space\color{black}(Δ+0.00)}$$ $${26.15\space\color{black}(Δ+0.00)}$$ $${8.84\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/ux-writing/index.md $${5.76\space\color{black}(Δ+0.00)}$$ $${9.25\space\color{black}(Δ+0.00)}$$ $${6.65\space\color{black}(Δ+0.00)}$$ $${63.38\space\color{black}(Δ+0.00)}$$ $${8.37\space\color{black}(Δ+0.00)}$$ $${33.65\space\color{black}(Δ+0.00)}$$ $${9.58\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/voice-tone-guidelines/index.md $${8.27\space\color{black}(Δ+0.00)}$$ $${10.89\space\color{black}(Δ+0.00)}$$ $${8.63\space\color{black}(Δ+0.00)}$$ $${56.36\space\color{black}(Δ+0.00)}$$ $${10.77\space\color{black}(Δ+0.00)}$$ $${39.01\space\color{black}(Δ+0.00)}$$ $${11.86\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/word-list/index.md $${6.26\space\color{black}(Δ+0.00)}$$ $${9.27\space\color{black}(Δ+0.00)}$$ $${7.26\space\color{black}(Δ+0.00)}$$ $${62.32\space\color{black}(Δ+0.00)}$$ $${9.16\space\color{black}(Δ+0.00)}$$ $${33.25\space\color{black}(Δ+0.00)}$$ $${10.52\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/write-for-developers/index.md $${8.35\space\color{black}(Δ+0.00)}$$ $${11.52\space\color{black}(Δ+0.00)}$$ $${9.24\space\color{black}(Δ+0.00)}$$ $${49.76\space\color{black}(Δ+0.00)}$$ $${10.74\space\color{black}(Δ+0.00)}$$ $${42.79\space\color{black}(Δ+0.00)}$$ $${11.85\space\color{black}(Δ+0.00)}$$
docs/sources/write/tooling-and-workflows/index.md $${7.53\space\color{black}(Δ+0.00)}$$ $${9.95\space\color{black}(Δ+0.00)}$$ $${8.36\space\color{black}(Δ+0.00)}$$ $${58.34\space\color{black}(Δ+0.00)}$$ $${9.37\space\color{black}(Δ+0.00)}$$ $${35.61\space\color{black}(Δ+0.00)}$$ $${10.58\space\color{black}(Δ+0.00)}$$
View metric targets | Metric | Range | Ideal score | | --- | --- | --- | | [AutomatedReadability](https://en.wikipedia.org/wiki/Automated_readability_index) | 6 (very easy read) to 14 (extremely difficult read) | 8 or less | | [ColemanLiau](https://en.wikipedia.org/wiki/Coleman%E2%80%93Liau_index) | 6 (very easy read) to 17 (extremely difficult read) | 9 or less | | [FleschKincaid](https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests) | 6 (very easy read) to 17 (extremely difficult read) | 8 or less | | [FleschReadingEase](https://en.wikipedia.org/wiki/Flesch%E2%80%93Kincaid_readability_tests) | 100 (very easy read) to 0 (extremely difficult read) | 70 or more | | [GunningFog](https://en.wikipedia.org/wiki/Gunning_fog_index) | 6 (very easy read) to 17 (extremely difficult read) | 10 or less | | [LIX](https://en.wikipedia.org/wiki/Lix_(readability_test)) | 20 (very easy read) to 60+ (extremely difficult read) | 35 or less | | [SMOG](https://en.wikipedia.org/wiki/SMOG) | 6 (very easy read) to 17 (extremely difficult read) | 10 or less |
jdbaldry commented 2 weeks ago

I just did a spot check but found this file has no review date when it's definitely been updated recently: docs/sources/write/style-guide/word-list/index.md

I don't think it's been formally reviewed since I introduced the review process for this repo: https://github.com/grafana/writers-toolkit/blame/63c5c56fd969f9b8b8cd787c9f5352959f77b468/docs/sources/write/style-guide/word-list/index.md shows nothing and neither does https://github.com/grafana/writers-toolkit/issues?q=is%3Aissue+word-list+is%3Aclosed

imatwawana commented 2 weeks ago

I just did a spot check but found this file has no review date when it's definitely been updated recently: docs/sources/write/style-guide/word-list/index.md

I don't think it's been formally reviewed since I introduced the review process for this repo: 63c5c56/docs/sources/write/style-guide/word-list/index.md (blame) shows nothing and neither does grafana/writers-toolkit/issues (word-list is:closed)

I guess that's not a blocker for this PR though?

jdbaldry commented 2 weeks ago

This PR adds the creation date to all pages which is a bit different to the review date. I'll confirm everything is getting into the review cycle separately I think.