[docs] Add detailed documentation guidelines

[colleenmcginnis]

What does this PR do?

From https://github.com/elastic/observability-docs/issues/1019:

Let's audit the documentation for our top 5 integrations. The descriptions can be improved so users have a better understanding of what benefit they offer, how Elastic can help with the user's use case, and persuade them to install the integration.

This PR proposes updated and more detailed documentation guidelines based on my experience adding context to the top five integrations in #3306, #3352, #3308, #3359, and #3393.

Guidelines like this can help standardize the structure and language across integrations, which may reduce friction for users who are interested in using more than one integration. But, they are also just guidelines and can be altered on a case-by-case basis as needed.

For the reviewer

• I'm open to any and all feedback on these guidelines! I am definitely not the expert on integrations -- I've mostly worked with the top five integrations (and a handful of others) -- so your input is critical!
• Do you agree with the goals stated at the beginning?
• Would it be helpful to work together on a list of assumptions we're comfortable making about the reader? For example, can we assume that they are familiar with Elastic and have created a deployment, but haven't used an integration before?
• I'm not sure what the true list of data types should be (logs, metrics, others?).

Checklist

• I have reviewed tips for building integrations and this pull request is aligned with them.
• I have verified that all data streams collect metrics or logs.
• I have added an entry to my package's changelog.yml file.
• I have verified that Kibana version constraints are current according to guidelines.

Author's Checklist

• Review by @bmorelli25
• Review by @jamiehynds
• Review by @jsoriano

Related issues

• https://github.com/elastic/observability-docs/issues/1019

[colleenmcginnis]

@bmorelli25 do you want to take a first look and then tag in others who should review?

[elasticmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Start Time: 2022-06-30T09:25:36.155+0000

• Duration: 103 min 46 sec

Test stats 🧪

Test	Results
Failed	0
Passed	5194
Skipped	7
Total	5201

🤖 GitHub comments

To re-run your PR in the CI, just comment with:

• /test : Re-trigger the build.

[elasticmachine]

🌐 Coverage report

Name	Metrics % (covered/total)	Diff
Packages	100.0% (265/265)	💚
Files	96.599% (426/441)	👍
Classes	96.599% (426/441)	👍
Methods	88.845% (4484/5047)	👍 0.095
Lines	89.947% (80975/90025)	👍
Conditionals	100.0% (0/0)	💚

[bmorelli25]

I think this document does a great job outlining the structure you came up with for https://github.com/elastic/observability-docs/issues/1019.

Like DeDe mentioned in today's meeting, and once the dev team weighs in, it'd be great to eventually automate the creation of a readme template. In the meantime, it might help to add a complete template to these docs that can easily be copy/pasted.

[jsoriano]

Nice, thanks!

Added some comments about the use of "data types" terms.

[colleenmcginnis]

@jamiehynds can you please take a look at these proposed guidelines? Thanks!

[colleenmcginnis]

Thanks for your comments @jamiehynds! There are a few remaining comments to be resolved, but I don't have enough context to propose general language/guidelines for them. Do you want to continue iterating here or accept the current guidelines and open issues to track the remaining comments?

[jamiehynds]

Thanks for your comments @jamiehynds! There are a few remaining comments to be resolved, but I don't have enough context to propose general language/guidelines for them. Do you want to continue iterating here or accept the current guidelines and open issues to track the remaining comments?

Sorry for the delay here @colleenmcginnis. I think I've responded to the outstanding comments. If you prefer to close this issue and open issues to track any remaining comments, totally fine with me.

[colleenmcginnis]

@bmorelli25 @jamiehynds @jsoriano do you have any other thoughts or suggestions? If not, can someone please give me an official ✅ ?

I opened three issues to track follow-up work:

• [docs] Add new docs template language to elastic-package create package elastic-package#880
• [docs] List assets included/associated with each integration's README #3625
• [docs] Update docs guidelines to include supported inputs for each integration #3628

[bmorelli25]

This is fantastic! Great work, @colleenmcginnis.

[jsoriano]

/test

[jsoriano]

Thanks @colleenmcginnis!