Page Comparison

...

• 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

• Confluence spaces 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?

    Types of spaces: Localized, Central (Internal / External)

  • Central Spaces - Spaces that are of interest across/outside of the org. These

    are generally functional or cross-functional link to other spaces and places and serve as a starting point for exploration. They encompass epics, systems, and groups that are of interest to the broader organization/community.

    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

...