Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add cascade and param info to Front Matter and Shortcodes topics #404

Merged
merged 8 commits into from
Dec 14, 2023

Conversation

clayton-cornell
Copy link
Contributor

This PR adds cascade and param info to Front Matter and shortcodes topics in the Writer's Toolkit

@clayton-cornell clayton-cornell added the type/docs Docs Squad label used across all Grafana Labs repos label Dec 14, 2023
Copy link
Contributor

github-actions bot commented Dec 14, 2023

Overall readability score: 60.85 (🟢 +0.02)

File Readability
index.md 71.49 (🟢 +0.11)
index.md 65.31 (🟢 +0.64)
View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File Readability FRE GF ARI CLI DCRS
index.md 71.49 56.86 8.63 9.5 10.37 6.65
  🟢 +0.11 🟢 +0 🔴 -0.03 🟢 +0.1 🟢 +0.06 🔴 -0.02
index.md 65.31 47.38 8.45 11.8 12.29 6.3
  🟢 +0.64 🟢 +0.3 🟢 +0.17 🟢 +0.1 🟢 +0.06 🟢 +0.02

Averages:

  Readability FRE GF ARI CLI DCRS
Average 60.85 47.79 9.56 11.6 12.05 7.31
  🟢 +0.02 🟢 +0.01 🟢 +0 🟢 +0 🟢 +0 🟢 +0
View metric targets
Metric Range Ideal score
Flesch Reading Ease 100 (very easy read) to 0 (extremely difficult read) 60
Gunning Fog 6 (very easy read) to 17 (extremely difficult read) 8 or less
Auto. Read. Index 6 (very easy read) to 14 (extremely difficult read) 8 or less
Coleman Liau Index 6 (very easy read) to 17 (extremely difficult read) 8 or less
Dale-Chall Readability 4.9 (very easy read) to 9.9 (extremely difficult read) 6.9 or less

docs/sources/write/shortcodes/index.md Outdated Show resolved Hide resolved
docs/sources/write/shortcodes/index.md Outdated Show resolved Hide resolved
Copy link
Member

@jdbaldry jdbaldry left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! I like this a lot. The cascade documentation is a useful subset of the Hugo docs. There are alternative forms of cascading front matter that can selectively target a page but I think keeping to this single form is valuable because it keeps things simple.

The `param` shortcode in the topic body text:

```markdown
Welcome to Grafana {{</* param PRODUCT_VERSION */>}}! Read on to learn about changes to dashboards and visualizations, data sources, security and authentication, and more.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should have exclamations in examples since they are discouraged by the style guide.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I copied this direct from the published docs :-) I'll remove it here.

@clayton-cornell
Copy link
Contributor Author

alternative forms of cascading

I saw that when I was reading up on cascade. I see it's also used for labels. I only documented the variable... thinking we could expand on this section as we need.

@clayton-cornell clayton-cornell merged commit 3e0d5ff into main Dec 14, 2023
6 checks passed
@clayton-cornell clayton-cornell deleted the add-cascading-var-guidelines branch December 14, 2023 13:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type/docs Docs Squad label used across all Grafana Labs repos
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants