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

@kdmccormickkdmccormick commented May 17, 2026

Copy link
Copy Markdown
Member

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

codecovBot commented May 17, 2026

Copy link
Copy Markdown

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 
FlagCoverage Δ
unittests93.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.

Co-Authored-By: Claude Opus 4.7 (1M Context) <noreply@anthropic.com>
@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 mainMay 18, 2026
7 checks passed
@kdmccormick
kdmccormick deleted the kdmccormick/readmes branch May 18, 2026 16:15
Sign up for freeto 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

@kdmccormick@feanil