grafana / writers-toolkit

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

Explain differences when working in the website repository #718

Closed jdbaldry closed 1 month ago

jdbaldry commented 1 month ago

Taylor noticed that these instructions cause confusion when they are applied to the website repository.

This change seeks to clarify those slight differences without going too deep because the audience is primarily going to be working in project repositories.

github-actions[bot] commented 1 month ago

Readability report

File AutomatedReadability ColemanLiau FleschKincaid FleschReadingEase GunningFog LIX SMOG
docs/sources/review/test-documentation-changes/index.md $${7.00\space\color{green}(Δ-0.01)}$$ $${10.27\space\color{green}(Δ-0.05)}$$ $${8.61\space\color{green}(Δ-0.01)}$$ $${52.28\space\color{green}(Δ+0.31)}$$ $${10.57\space\color{red}(Δ+0.04)}$$ $${40.97\space\color{green}(Δ-0.13)}$$ $${11.21\space\color{red}(Δ+0.03)}$$
docs/sources/shared/make-help.md $${8.45\space\color{red}(Δ+0.05)}$$ $${11.60\space\color{green}(Δ-0.13)}$$ $${11.07\space\color{red}(Δ+0.48)}$$ $${36.81\space\color{red}(Δ-2.61)}$$ $${12.94\space\color{green}(Δ-0.04)}$$ $${43.18\space\color{red}(Δ+1.96)}$$ $${13.02\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 |