Doc updates from review with @atravitz

[dotsdl]

This PR includes a set of doc updates from recent review with @atravitz.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.47%. Comparing base (f75acc8) to head (a8b8317).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #461      +/-   ##
==========================================
- Coverage   78.49%   78.47%   -0.03%     
==========================================
  Files          29       29              
  Lines        4762     4762              
==========================================
- Hits         3738     3737       -1     
- Misses       1024     1025       +1     

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.