Skip to content

docs: Rework READMEs#52

Merged
kdmccormick merged 2 commits into
mainfrom
kdmccormick/readmes
May 18, 2026
Merged

docs: Rework READMEs#52
kdmccormick merged 2 commits into
mainfrom
kdmccormick/readmes

Conversation

@kdmccormick
Copy link
Copy Markdown
Member

@kdmccormick kdmccormick commented May 17, 2026

WIP

Preview: https://github.com/openedx/sample-plugin/blob/kdmccormick/readmes/README.md

Written by Claude from this prompt:


Hi, I'd like to rework all READMEs (excluding the one in docs/decisions).

General principles:

  • Prioritize the ability of someone jumping into the readme first the first time to (i) understsand the purpose and (ii) find instructions of the common two use cases (local dev with Tutor, local dev without Tutor). Details are de-emphasized by being moved lower nested in more specific READMEs.
  • One source-of-truth for any set of instructions. When helpful, link to the source of truth rather than repeating it.
  • Avoid "AI-isms" (sorry, Claude :), such as headings like "Key X" and phrases like "The most important thing: ...".
  • Avoid sprawling lists of bullet points. We don't need a link to every resource!

Here's my proposed structure--loosely, these are ideas, not headings. Feel free to suggest alternatives and discuss with me.

  • ./README.rst
    • What is it?
    • Table linking to sub-plugins
    • Development with Tutor
    • Development without Tutor
    • Getting help
  • <sub-plugin>/README.rst
    • What is it?
    • How to use it -> just link back up to top level README
    • How does it work?

Other guidance:

  • Preserve existing TODOs
  • Ask for questions eagerly
  • Don't make assumptions about factual content. Happy to explain any technical information that's missing.

@codecov
Copy link
Copy Markdown

codecov Bot commented May 17, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.04%. Comparing base (e7a17d1) to head (b51b811).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main      #52   +/-   ##
=======================================
  Coverage   93.04%   93.04%           
=======================================
  Files          16       16           
  Lines         503      503           
  Branches       18       18           
=======================================
  Hits          468      468           
  Misses         24       24           
  Partials       11       11           
Flag Coverage Δ
unittests 93.04% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@kdmccormick kdmccormick force-pushed the kdmccormick/readmes branch from 7ac93bd to 82438f4 Compare May 18, 2026 16:05
Co-Authored-By: Claude Opus 4.7 (1M Context) <noreply@anthropic.com>
@kdmccormick kdmccormick force-pushed the kdmccormick/readmes branch from 82438f4 to b8f46f5 Compare May 18, 2026 16:06
@kdmccormick kdmccormick marked this pull request as ready for review May 18, 2026 16:07
Co-Authored-By: Claude Opus 4.7 (1M Context) <noreply@anthropic.com>
@kdmccormick kdmccormick merged commit b5eae7c into main May 18, 2026
7 checks passed
@kdmccormick kdmccormick deleted the kdmccormick/readmes branch May 18, 2026 16:15
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.

2 participants