Skip to content

Conversation

colleenmcginnis
Copy link
Contributor

@colleenmcginnis colleenmcginnis commented May 9, 2022

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 adds more context the System 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.
  • Pushes content about special cases and exceptions into a "Troubleshooting" section.
  • Standardizes subheadings per dataset.

For the reviewer

  • From an accessibility standpoint, it may be better to use headings instead of **Exported fields** since it acts like a heading. Do you think that's worth pursuing? Where is that defined?
  • Does the opening sentence accurately capture the extent of systems that you can monitor? (I know just mentioning servers was one issue with the current version of the description.)
  • 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. Applied to PRs that modify *.md files. enhancement New feature or request Team:Docs Label for the Observability docs team labels May 9, 2022
@colleenmcginnis colleenmcginnis requested a review from bmorelli25 May 9, 2022 22:17
@colleenmcginnis colleenmcginnis self-assigned this May 9, 2022
@elasticmachine
Copy link

elasticmachine commented May 9, 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:06:32.178+0000

  • Duration: 15 min 50 sec

Test stats 🧪

Test Results
Failed 0
Passed 270
Skipped 0
Total 270

🤖 GitHub comments

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

  • /test : Re-trigger the build.

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.

Just a few comments from me before this is passed on to the dev team. This is a huge improvement! And it builds in the new docs system 😁

Screen Shot 2022-05-09 at 4 18 41 PM

@bmorelli25
Copy link
Member

From an accessibility standpoint, it may be better to use headings instead of Exported fields since it acts like a heading. Do you think that's worth pursuing? Where is that defined?

I agree. To me it makes sense for Exported fields to be the same level heading as Supported operating systems since they're both topics within each dataset.

@elasticmachine
Copy link

elasticmachine commented May 10, 2022

🌐 Coverage report

Name Metrics % (covered/total) Diff
Packages 100.0% (3/3) 💚
Files 100.0% (4/4) 💚 3.44
Classes 100.0% (4/4) 💚 3.44
Methods 59.74% (46/77) 👎 -29.189
Lines 98.782% (2676/2709) 👍 8.831
Conditionals 100.0% (0/0) 💚

@colleenmcginnis colleenmcginnis marked this pull request as ready for review May 12, 2022 19:17
@colleenmcginnis colleenmcginnis requested a review from a team as a code owner May 12, 2022 19:17
@cmacknz cmacknz requested a review from fearful-symmetry May 12, 2022 19:19
Copy link
Contributor

@fearful-symmetry fearful-symmetry left a comment

Choose a reason for hiding this comment

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

Changes TGTM.

@colleenmcginnis colleenmcginnis merged commit e1d65a9 into elastic:main Jun 21, 2022
@colleenmcginnis colleenmcginnis deleted the top-five-audit-system 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. Applied to PRs that modify *.md files. 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.

4 participants