grafana / writers-toolkit

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

Revert "Docs: remove to do note" #734

Closed jdbaldry closed 3 months ago

jdbaldry commented 3 months ago

Reverts grafana/writers-toolkit#732

I think the note is a useful reminder to review the issue. I think it can be removed when the issue is resolved, either as a won't do or when it's fixed.

It's this note that prompted me to bump the issue in Writers' Toolkit as I encountered it when reviewing the page for accuracy.

github-actions[bot] commented 3 months ago

Readability report

File AutomatedReadability ColemanLiau FleschKincaid FleschReadingEase GunningFog LIX SMOG
docs/sources/structure/topic-types/visualization/index.md $${7.42\space\color{black}(Δ+0.00)}$$ $${10.98\space\color{black}(Δ+0.00)}$$ $${9.80\space\color{black}(Δ+0.00)}$$ $${42.80\space\color{black}(Δ+0.00)}$$ $${10.08\space\color{black}(Δ+0.00)}$$ $${38.49\space\color{black}(Δ+0.00)}$$ $${10.85\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 |
clayton-cornell commented 3 months ago

Before approving/merging, pinging @imatwawana as originator.

I agree here. Remove the comment/note once the issue is completed, not before. It's a useful bit of info while things are in progress, and isn't published. Mark the note removal as a task item in the linked issue so it isn't forgotten?

imatwawana commented 3 months ago

So I'm just gonna keep getting periodic bumps from you if I haven't worked on this issue, lol?

jdbaldry commented 3 months ago

Closing in favor of https://github.com/grafana/writers-toolkit/pull/736