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 Windows integration documentation #3352

Merged
merged 7 commits into from
Jun 21, 2022

Conversation

colleenmcginnis
Copy link
Contributor

@colleenmcginnis colleenmcginnis commented May 12, 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 Windows 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 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 "Logs" and "Metrics" are in the context of the integration.
  • Adds a "Requirements" section:
    • Reinforces how this integration fits into the larger Elastic system.
    • Mentions that different permission levels may be required for various datasets, but prompts the reader to see the reference sections for detail instead of listing permission information here.
  • Points the reader to the Getting started guide for step-by-step "Setup" instructions.

For the reviewer

  • I had trouble coming up with a more specific example, but maybe that's ok?
  • We say that some datasets "may require dedicated permissions", but we don't provide any details. Are there details we can add that are similar to those in the System integration documentation?
  • 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 12, 2022
@colleenmcginnis colleenmcginnis self-assigned this May 12, 2022
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.

Haven't tested the build yet, but everything looks good. One small nit.

packages/windows/_dev/build/docs/README.md Outdated Show resolved Hide resolved
@elasticmachine
Copy link

elasticmachine commented May 12, 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-21T19:20:55.440+0000

  • Duration: 17 min 50 sec

Test stats 🧪

Test Results
Failed 0
Passed 126
Skipped 0
Total 126

🤖 GitHub comments

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

  • /test : Re-trigger the build.

@elasticmachine
Copy link

elasticmachine commented May 12, 2022

🌐 Coverage report

Name Metrics % (covered/total) Diff
Packages 100.0% (4/4) 💚
Files 87.5% (7/8) 👎 -9.06
Classes 87.5% (7/8) 👎 -9.06
Methods 84.884% (73/86) 👎 -4.045
Lines 93.376% (4962/5314) 👍 3.425
Conditionals 100.0% (0/0) 💚

@colleenmcginnis colleenmcginnis marked this pull request as ready for review May 19, 2022 19:14
@colleenmcginnis colleenmcginnis requested review from a team as code owners May 19, 2022 19:14
@faec faec removed their request for review May 19, 2022 19:55
packages/windows/_dev/build/docs/README.md Outdated Show resolved Hide resolved

### Forwarded

The Windows `forwarded` dataset provides events from the Windows
`ForwardedEvents` event log. The fields will be the same as the
channel specific datasets.

#### Permissions

This data should be available without elevated permissions.
Copy link
Member

Choose a reason for hiding this comment

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

The permissions requirements seem odd to mention because AFAIK the whole Elastic Agent is required to run as a service account which has elevated permissions.

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 included this because in the System integration, there are different levels of permission needed for different data streams (see this PR), but if that's not the case for the Windows integration I can remove these!

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 Integration:windows Windows Team:Docs Label for the Observability docs team
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants