Add data sources writing guidelines

[lwandz13]

Adding the data sources writing guideline to Writers' Toolkit. Please ensure that:

• The formatting looks good
• The information is clearly presented

Users outside Grafana will see this, so ensure that no proprietary information is included.

• I've used a relevant pull request (PR) title.
• I've added a link to any relevant issues in the PR description.
• I've checked my changes on the deploy preview and they look good.
• I've added an entry to the What's new page (only required for notable changes).

[github-actions]

Readability report

File	AutomatedReadability	ColemanLiau	FleschKincaid	FleschReadingEase	GunningFog	LIX	SMOG
docs/sources/contribute/data-source-writing-guide/index.md	$${8.24\space\color{black}(Δ+0.00)}$$	$${12.58\space\color{black}(Δ+0.00)}$$	$${8.98\space\color{black}(Δ+0.00)}$$	$${44.49\space\color{black}(Δ+0.00)}$$	$${10.92\space\color{black}(Δ+0.00)}$$	$${40.35\space\color{black}(Δ+0.00)}$$	$${10.74\space\color{black}(Δ+0.00)}$$
docs/sources/write/front-matter/index.md	$${6.67\space\color{black}(Δ+0.00)}$$	$${9.13\space\color{black}(Δ+0.00)}$$	$${7.80\space\color{black}(Δ+0.00)}$$	$${61.31\space\color{black}(Δ+0.00)}$$	$${9.81\space\color{black}(Δ+0.00)}$$	$${35.79\space\color{black}(Δ+0.00)}$$	$${10.84\space\color{black}(Δ+0.00)}$$
docs/sources/write/shortcodes/index.md	$${7.01\space\color{black}(Δ+0.00)}$$	$${10.38\space\color{black}(Δ+0.00)}$$	$${7.91\space\color{black}(Δ+0.00)}$$	$${56.84\space\color{black}(Δ+0.00)}$$	$${9.18\space\color{black}(Δ+0.00)}$$	$${39.25\space\color{black}(Δ+0.00)}$$	$${10.53\space\color{black}(Δ+0.00)}$$
docs/sources/write/style-guide/inclusive-writing/index.md	$${6.43\space\color{black}(Δ+0.00)}$$	$${9.78\space\color{black}(Δ+0.00)}$$	$${7.72\space\color{black}(Δ+0.00)}$$	$${57.52\space\color{black}(Δ+0.00)}$$	$${10.00\space\color{black}(Δ+0.00)}$$	$${37.50\space\color{black}(Δ+0.00)}$$	$${10.76\space\color{black}(Δ+0.00)}$$

View metric targets

Metric	Range	Ideal score
AutomatedReadability	6 (very easy read) to 14 (extremely difficult read)	8 or less
ColemanLiau	6 (very easy read) to 17 (extremely difficult read)	9 or less
FleschKincaid	6 (very easy read) to 17 (extremely difficult read)	8 or less
FleschReadingEase	100 (very easy read) to 0 (extremely difficult read)	70 or more
GunningFog	6 (very easy read) to 17 (extremely difficult read)	10 or less
LIX	20 (very easy read) to 60+ (extremely difficult read)	35 or less
SMOG	6 (very easy read) to 17 (extremely difficult read)	10 or less

[github-actions]

💻 Deploy preview available:

• https://deploy-preview-writers-toolkit-1221-zb444pucvq-vp.a.run.app/docs/writers-toolkit/

[jdbaldry]

Thanks for adding this! This is great guidance for data source documentation.

I still think this document makes more sense in the Writers' Toolkit IA under Structure since it primarily discusses structuring data source documentation.

@chri2547 wdyt?

[chri2547]

• https://deploy-preview-writers-toolkit-1221-zb444pucvq-vp.a.run.app/docs/writers-toolkit/

@jdbaldry , @lwandz13 - yes, this kind of content belongs in the Structure area, and it should include screenshots that show the parts of the docs. Because data source docs have multiple documents, I would nest them under a parent, like:

Structure
|-----Data source docs writing guidelines landing page
|------Intro (with descriptions and screen shot)
|------Configure (with descriptions and screen shot)
|------Query editor (with descriptions and screen shot)
|------Template variables (with descriptions and screen shot)

In addition, each of the doc types listed above should have a corresponding template.

[lwandz13]

@chri2547 @jdbaldry Hear me out on this: I think this doc belongs under Contribute, since it provides guidance for both internal and external developers on how to create and update data source documentation. Placing it there also helps ensure that information about contributing to non–Grafana managed data sources is easy to find and consistent with the rest of our docs. Thoughts? If you still feel very strongly that I move this, I will.

[jdbaldry]

since it provides guidance for both internal and external developers on how to create and update data source documentation.

I think that applies to all of Writers' Toolkit documentation though, right?

Placing it there also helps ensure that information about contributing to non–Grafana managed data sources is easy to find and consistent with the rest of our docs.

I'm no expert on IA, I'm not sure if it's easier to find in Contribute or Structure. I guess if I were a data source dev, I wouldn't know to click on either to find documentation for how to write my data source documentation