[docs] Add detailed documentation guidelines by colleenmcginnis · Pull Request #3433 · elastic/integrations

colleenmcginnis · 2022-05-25T22:42:21Z

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 · 2022-05-25T22:43:10Z

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

elasticmachine · 2022-05-26T01:04:45Z

💚 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 · 2022-05-26T01:05:00Z

🌐 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 · 2022-06-06T19:29:03Z

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

update generated docs

@andrewkroh

* first draft of windows integration edits * update changelog, update manifest, build README * address initial feedback * address feedback from @andrewkroh * align with guidelines in #3433

* first draft of linux metrics integration edits * Update packages/linux/changelog.yml * align with guidelines in #3433

colleenmcginnis · 2022-06-22T19:36:57Z

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 · 2022-06-28T08:58:56Z

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 · 2022-06-29T21:03:34Z

@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 · 2022-06-30T09:24:57Z

/test

jsoriano

Thanks @colleenmcginnis!

@ishleenk17

* first draft of nginx integration edits * add pr link * align with guidelines in #3433 * address feedback from @ishleenk17

@bmorelli25

* first draft of system integration edits wording * update changelog, update manifest, build README * clean up changelog.yml * address feedback from @bmorelli25 * align with guidelines in elastic#3433

@bmorelli25

* first draft of aws integration edits * update changelog, update manifest, build README * actually build READMEs * address feedback from @bmorelli25 * remove relative links * updated generated READMEs * address feedback on build errors * align with guidelines in elastic#3433 update generated docs * address feedback from @kaiyan-sheng

@andrewkroh

* first draft of windows integration edits * update changelog, update manifest, build README * address initial feedback * address feedback from @andrewkroh * align with guidelines in elastic#3433

…c#3359) * first draft of linux metrics integration edits * Update packages/linux/changelog.yml * align with guidelines in elastic#3433

@jamiehynds

* first draft of updated documentation guidelines * clean up * copy edit * address initial feedback * use data stream instead of data type, dataset * address feedback from @jamiehynds * include the log types we support out of the box

@ishleenk17

* first draft of nginx integration edits * add pr link * align with guidelines in elastic#3433 * address feedback from @ishleenk17

Colleen McGinnis added 2 commits May 25, 2022 15:51

first draft of updated documentation guidelines

61fe1a3

clean up

1ea8000

colleenmcginnis added documentation Improvements or additions to documentation. Applied to PRs that modify *.md files. enhancement New feature or request Team:Docs Label for the Observability docs team labels May 25, 2022

colleenmcginnis requested a review from bmorelli25 May 25, 2022 22:42

colleenmcginnis self-assigned this May 25, 2022

bmorelli25 reviewed Jun 1, 2022

View reviewed changes

Comment thread docs/documentation_guidelines.md Outdated

copy edit

13dc132

colleenmcginnis marked this pull request as ready for review June 1, 2022 18:41

colleenmcginnis requested a review from a team as a code owner June 1, 2022 18:41

colleenmcginnis requested a review from jamiehynds June 1, 2022 18:41

jsoriano reviewed Jun 2, 2022

View reviewed changes

Comment thread docs/documentation_guidelines.md Outdated

Comment thread docs/documentation_guidelines.md

Comment thread docs/documentation_guidelines.md Outdated

Comment thread docs/documentation_guidelines.md Outdated

Colleen McGinnis added 2 commits June 6, 2022 13:56

address initial feedback

62d1d2b

use data stream instead of data type, dataset

700c683

colleenmcginnis pushed a commit to colleenmcginnis/integrations that referenced this pull request Jun 6, 2022

align with guidelines in elastic#3433

c0abc2d

update generated docs

colleenmcginnis pushed a commit to colleenmcginnis/integrations that referenced this pull request Jun 6, 2022

align with guidelines in elastic#3433

c9276e4

ruflin requested a review from akshay-saraswat June 7, 2022 13:02

colleenmcginnis pushed a commit to colleenmcginnis/integrations that referenced this pull request Jun 7, 2022

align with guidelines in elastic#3433

63a13b6

colleenmcginnis pushed a commit to colleenmcginnis/integrations that referenced this pull request Jun 7, 2022

align with guidelines in elastic#3433

2721d75

colleenmcginnis pushed a commit to colleenmcginnis/integrations that referenced this pull request Jun 7, 2022

align with guidelines in elastic#3433

22fe0e8

jamiehynds reviewed Jun 15, 2022

View reviewed changes

Comment thread docs/documentation_guidelines.md

jamiehynds reviewed Jun 15, 2022

View reviewed changes

Comment thread docs/documentation_guidelines.md

jamiehynds reviewed Jun 15, 2022

View reviewed changes

Comment thread docs/documentation_guidelines.md

jamiehynds reviewed Jun 15, 2022

View reviewed changes

Comment thread docs/documentation_guidelines.md

colleenmcginnis added a commit that referenced this pull request Jun 21, 2022

[docs] Add context to Linux Metrics integration documentation (#3359)

e68e4ab

* first draft of linux metrics integration edits * Update packages/linux/changelog.yml * align with guidelines in #3433

Colleen McGinnis added 2 commits June 22, 2022 13:32

Merge branch 'main' into top-five-audit-guidelines

7f8e047

address feedback from @jamiehynds

d778b31

colleenmcginnis requested a review from jamiehynds June 22, 2022 20:54

bmorelli25 mentioned this pull request Jun 22, 2022

Add context to Azure integration documentation #3072

Merged

Colleen McGinnis added 2 commits June 29, 2022 11:26

Merge branch 'main' into top-five-audit-guidelines

c4abf27

include the log types we support out of the box

05a0d3e

bmorelli25 approved these changes Jun 30, 2022

View reviewed changes

jsoriano approved these changes Jun 30, 2022

View reviewed changes

colleenmcginnis merged commit 7a17e3b into elastic:main Jun 30, 2022

colleenmcginnis deleted the top-five-audit-guidelines branch June 30, 2022 15:18

colleenmcginnis mentioned this pull request Jun 30, 2022

Update integration docs for individual AWS/Amazon services #3572

Closed

24 tasks

colleenmcginnis pushed a commit that referenced this pull request Jul 7, 2022

[docs] Add context to Nginx integration documentation (#3393)

ce91bf3

* first draft of nginx integration edits * add pr link * align with guidelines in #3433 * address feedback from @ishleenk17

colleenmcginnis mentioned this pull request Jul 27, 2022

[docs] Update Jamf docs to align with docs guidelines #3862

Merged

8 tasks

bmorelli25 mentioned this pull request Aug 23, 2022

Add package readme howto guide elastic/elastic-package#936

Merged

colleenmcginnis mentioned this pull request Aug 30, 2022

Add docs template language to elastic-package create package elastic/elastic-package#954

Merged

4 tasks

Navigation Menu

Uh oh!

[docs] Add detailed documentation guidelines - #3433

[docs] Add detailed documentation guidelines#3433
colleenmcginnis merged 9 commits into
elastic:mainfrom
colleenmcginnis:top-five-audit-guidelines

colleenmcginnis commented May 25, 2022 •

edited

Loading

colleenmcginnis commented May 25, 2022

elasticmachine commented May 26, 2022 •

edited

Loading

Build stats

Test stats 🧪

elasticmachine commented May 26, 2022 •

edited

Loading

bmorelli25 left a comment

Uh oh!

jsoriano left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colleenmcginnis commented Jun 6, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colleenmcginnis commented Jun 22, 2022

jamiehynds commented Jun 28, 2022

colleenmcginnis commented Jun 29, 2022

bmorelli25 left a comment

jsoriano commented Jun 30, 2022

jsoriano left a comment

Labels

5 participants

Uh oh!

Conversation

colleenmcginnis commented May 25, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do?

For the reviewer

Checklist

Author's Checklist

Related issues

colleenmcginnis commented May 25, 2022

elasticmachine commented May 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

💚 Build Succeeded

Build stats

Test stats 🧪

🤖 GitHub comments

elasticmachine commented May 26, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🌐 Coverage report

bmorelli25 left a comment

Choose a reason for hiding this comment

Uh oh!

jsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colleenmcginnis commented Jun 6, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colleenmcginnis commented Jun 22, 2022

jamiehynds commented Jun 28, 2022

colleenmcginnis commented Jun 29, 2022

bmorelli25 left a comment

Choose a reason for hiding this comment

jsoriano commented Jun 30, 2022

jsoriano left a comment

Choose a reason for hiding this comment

Labels

5 participants

colleenmcginnis commented May 25, 2022 •

edited

Loading

elasticmachine commented May 26, 2022 •

edited

Loading

elasticmachine commented May 26, 2022 •

edited

Loading