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

Refactor README.md #6881

Merged
merged 2 commits into from
Nov 18, 2024
Merged

Refactor README.md #6881

merged 2 commits into from
Nov 18, 2024

Conversation

jack-berg
Copy link
Member

@jack-berg jack-berg commented Nov 15, 2024

Now that I've finished refactoring opentelemetry.io Java docs, I figured its time to give the project README a face lift.

The current README tries to perform some of the functions which are now done at a higher level in opentelemetry.io. The result is cluttered and out of date.

Ideas in this PR:

  • The readme should more or less be a routing page, with just enough details on various key subjects to connect with a reader and link to a more exhaustive document
  • Start with terse explanation of repository, quickly redirecting users to the opentelemetry.io source of truth for more details
  • Quick introduction of things like requirements, releases, compatibility, contributing, but link out to more detailed explanations in VERSIONING.md, CONTRIBUTING.md, RELEASING.md, etc.
  • Move tables summarizing artifacts to collapsible sections, with API and SDK sections expanded by default
  • Move various gradle / maven instructions to collapsible sections, with gradle instructions expanded by default

Result is README reduces from ~8200 pixels of content to ~4400 (~46%).

Hopefully this reduction makes it easier for users to consume the content and reach the information they need faster.

To compare and contrast, see current and newly proposed.

@jack-berg jack-berg requested a review from a team as a code owner November 15, 2024 20:43
Copy link

codecov bot commented Nov 15, 2024

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.30%. Comparing base (ca98fc5) to head (b578638).
Report is 2 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff            @@
##               main    #6881   +/-   ##
=========================================
  Coverage     90.30%   90.30%           
  Complexity     6589     6589           
=========================================
  Files           729      729           
  Lines         19767    19767           
  Branches       1944     1944           
=========================================
  Hits          17851    17851           
  Misses         1325     1325           
  Partials        591      591           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Copy link
Member

@jaydeluca jaydeluca left a comment

Choose a reason for hiding this comment

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

looks nice

@jack-berg jack-berg merged commit bd31b45 into open-telemetry:main Nov 18, 2024
25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants