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

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

Merged
merged 4 commits into from
Jun 21, 2022

Conversation

colleenmcginnis
Copy link
Contributor

@colleenmcginnis colleenmcginnis commented May 16, 2022

What does this PR do?

From elastic/observability-docs#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 adds more context the Linux Metrics integration including:

  • Applies a new proposed structure to be applied across top integrations (overview, data types, requirements/prerequisites, setup, reference).
  • Creates a soft division between guide-like content and reference-like content.
  • Adds context to the "Overview":
    • Acknowledges the relationship between this integration and the larger ecosystem of Elastic products.
    • Provides [placeholder text for] a basic example to illustrate how this integration may be useful.
  • Adds a "Data types" section:
    • Provides a high-level overview of the kind of data that is collected. (It's difficult to derive a summary from just the reference sections since they're so long.)
    • Reinforces what "Metrics" are in the context of the integration.
  • Adds a "Requirements" section:
    • Reinforces how this integration fits into the larger Elastic system.
    • Mentions trouble that might occur related to permission levels.
  • Points the reader to the Getting started guide for step-by-step "Setup" instructions.

For the reviewer

  • I had trouble coming up with an example. Can anyone help me fill in the blanks in the third paragraph?
  • In some places this is referred to as the "Linux integration" and in others it's referred to as the "Linux Metrics integration". Which is preferred?
  • I noticed we're using some terms inconsistently. Here we use the term "data stream" to describe the various metrics, but in the Windows ([docs] Add context to Windows integration documentation #3352) and System ([docs] Add context to System integration documentation #3306) integration docs we refer to them as "datasets". Do these two terms actually mean the same thing or should they be different? If they mean the same thing, which is preferred?
  • Open to any and all feedback on language and truthiness!

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 TBD (Integrations team)

Related issues

@colleenmcginnis colleenmcginnis added documentation Improvements or additions to documentation enhancement New feature or request Team:Docs Label for the Observability docs team labels May 16, 2022
@colleenmcginnis colleenmcginnis self-assigned this May 16, 2022
@elasticmachine
Copy link

elasticmachine commented May 16, 2022

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS
Pipeline View Test View Changes Artifacts preview preview

Expand to view the summary

Build stats

  • Start Time: 2022-06-07T14:39:27.609+0000

  • Duration: 20 min 40 sec

Test stats 🧪

Test Results
Failed 0
Passed 25
Skipped 0
Total 25

🤖 GitHub comments

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

  • /test : Re-trigger the build.

@elasticmachine
Copy link

elasticmachine commented May 16, 2022

🌐 Coverage report

Name Metrics % (covered/total) Diff
Packages 100.0% (0/0) 💚
Files 100.0% (0/0) 💚 3.432
Classes 100.0% (0/0) 💚 3.432
Methods 51.515% (17/33) 👎 -37.374
Lines 100.0% (0/0) 💚 10.242
Conditionals 100.0% (0/0) 💚

Copy link
Member

@bmorelli25 bmorelli25 left a comment

Choose a reason for hiding this comment

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

The layout and general flow look good. No feedback from me on this one.

I'll leave your "Reviewers" questions for the engineering team.

@colleenmcginnis colleenmcginnis marked this pull request as ready for review May 19, 2022 19:15
@colleenmcginnis colleenmcginnis requested a review from a team as a code owner May 19, 2022 19:15
@rdner rdner removed their request for review June 15, 2022 08:27
@colleenmcginnis colleenmcginnis merged commit e68e4ab into elastic:main Jun 21, 2022
@colleenmcginnis colleenmcginnis deleted the top-five-audit-linux branch June 21, 2022 19:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation enhancement New feature or request Team:Docs Label for the Observability docs team
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants