The highest-level goals for this doc are to:

• Clarify what goes where, with the goal of single source-of-truth.

• Establish best-practices for how to use our documentation tools.

What goes where?

OEP-19 provides guidance on long-term developer documentation, and proposes the following:

• Long-term developer docs should live in GitHub.

  • This includes things like design docs, arch decisions, READMEs, how-tos, API reference.

  • Depending on scope, they can live in either the repos they document, or broader documentation repos (e.g. edx-documentation) which get built to Read-the-docs.

• Developer notes should be in Confluence.

Extending the guidance above:

• GitHub, followed by Confluence should be seen as the “canonical” sources of information. These established sources allow information to be discoverable & centralized.

• Confluence is good for docs that don’t fit neatly into a repo or are not strictly code/feature related. Some examples:

  • Organizationally-linked docs - Documents pertaining to a team/project/theme that are scoped to a group in edX e.g. Theme feature planning docs, team meeting notes.

  • Non-code resource docs - Resources like system architecture diagrams, or brand resources that have an Open edX scope, but are too high-level for Read-the-docs.

  • Internal developer docs - Documentation that should be strictly internal and is not tied to a private repo e.g. internal debugging/system notes.

• Docs may be written in other tools for the sake of collaborative tooling, rich diagram editing, etc. but must be discoverable (linked) from GitHub or Confluence and, ideally, moved into one of these when complete.

Documentation tools best practices

General

• Every doc should have a clear audience and owner. Bonus points for establishing that in the header of the doc/space.

• Discoverability is key. Establish entry points and have links out to disconnected docs.

• Linking > Duplicating. When possible, establish a single source of truth. Link where necessary. It means you only have to keep one doc up to date and it is clearer when something is canonical.

• Archive more. More docs = more docs to maintain. If docs are out of date, we should be empowering folks to signal that they are out of date or just archive them.

GitHub / Read the Docs

Following OEP-19, documentation around code generally gets stored in GitHub (either to be read in GitHub or published to Read-the-Docs). This allows it to be searchable and live near the code it describes. It also describes different types of docs in GitHub and where to store them:

• Repo specific docs should live in the repos they document and include the following types:

  • ADRs, READMEs, and How-to’s should live in the /docs folder of a repo and be linked from the repo-level readme.

• Cross-repo docs go in edx-documentation to be published to Read-the-docs.

Confluence

Best-practices

• Docs in Confluence are generally scoped and provide access rights based on the space. Spaces should have clear purposes and audiences.

  • When navigating a space, consider:

    • Purpose (day-to-day planning; education; history)

    • Audience (just the writing team, or broader?)

    • Who can write? Who can read?

  • Central Spaces - Spaces that are of interest across/outside of the org. These exist separately from Localized spaces, which are targeted to individuals/teams. Centralized spaces are further split into 2 categories based on access-rights:

    • Internal - Internal resources, private to edX.

      • Company internal resources (IT, HR, Facilities)

      • https://openedx.atlassian.net/wiki/spaces/ENG

      • Cross-functional team spaces (Working Groups, DEI, Hackathon, edX Cares)

      • Themes (Content, Engagement, etc.)

    • External - Spaces of interest to the Open edX community, public by nature.

      • https://openedx.atlassian.net/wiki/spaces/AC

      • Shared resource spaces UX, Brand, etc.

  • Localized Spaces - Used for specific teams/individuals, not meant to be shared/understand by those outside of the group the space is meant to serve.

    • Team / squad / personal spaces

• Every space should have an owner.

  • The owner should “watch” the entire space and is responsible for keeping the space clean, organized and useful.

• Duplication of information should be avoided, cross link when possible. You can also /include one confluence page into another if you want the info to be seen together.

• Archive more. Anyone stumbling across an out-of-date page should be empowered to update or archive it. Alternatively, for spaces with more restrictive archiving rights, they may request update/archive using the following signals:

  1. #updates-needed - Propose adding this new tag to help space owners find out-of-date pages.

  2. #archive - Propose adding this new tag to help space owners find pages that should be archived/deleted.

  3. Investigate tooling/watching for this tag for space owners so they can be notified about these.

Student blog / edX Blog / Open edX Blog / Open edX Discuss

Google docs / Miro / Figma / Other

• For temporary writing/collaborating but not permanent storage: move them somewhere else (generally Confluence) when done. Delete the old doc or replace the content with a link to the new page after the documentation has been moved.

• For permanent docs (e.g. diagrams that can’t be done with other tools) they should be linked to a permanent home (Confluence/GitHub)