/
Writing Open edX Docs with Claude

Writing Open edX Docs with Claude

Hi all, I've been experimenting writing documentation with Claude, and it works incredibly well! I want to share what prompts you should load into Claude's memory before beginning writing docs with it, to ensure that your docs automagically adhere to our conventions.

Here's a Gist of what to feed into Claude’s memory bank: Feed these prompts into Claude to begin writing Open edX documentation!

ReadTheDocs blocks AI access, so you will have to load in the raw RST files from GitHub when referencing other docs; if you're not sure how to find these, it's not difficult from the UI, but it is annoying.

  • Click the "Suggest Edit" icon from the GitHub action menu on any docs page

    image-20260409-173626.png

  • Go back one level on GitHub (in the screenshot, by clicking on "Source")

    image-20260409-173638.png

  • From the file page, reselect the page you were looking at, then clicking the "Raw" button in the right corner, and feed that URL into Claude. The URL will start with “raw.githubusercontent.com”, like this: https://raw.githubusercontent.com/openedx/docs.openedx.org/refs/heads/main/source/documentors/references/templates/doc_reference_template.rst

    image-20260409-173653.png

Claude can’t natively read docs from Confluence, although this is very helpful to have! Add a Confluence connector here: https://claude.ai/settings/connectors

  • Click “Browse Connectors”

  • Find “Atlassian Rovo”

  • Authenticate with your Open edX Confluence user.

Note that linking code (especially pull requests) is helpful context for Claude to have, and it can natively read github code & PRs (however if you do too much you may end up rate-limited and need to wait a bit to finish up)

Things you’ll likely need to fix once Claude has generated your docs:

  • The cross-references it generates are often directionally correct (like, yes, a cross-reference here would be great) but do not actually contain the correct :ref: target, so you'll need to check those. Claude will often share its assumptions so you know what to check.

  • You'll also need to manually edit to add in screenshots.

Here's a prompt log that generated a first draft of documentation based on one comment & some PRs from the Libraries team: Docs PR #1425 Claude log and the way the PR looks is like this: Libraries concept doc and override docs by sarina · Pull Request #1425 · openedx/docs.openedx.org

Please reach out to @Sarina Canelake if you want to do a screenshare session or have any questions!