Page Comparison

...

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

  • The audience dictates location/access rights e.g. is the doc/space tied to a repo, team, theme, or functional group; is it public or private.

  • The owner is responsible for lifecycle management. This means setting location/access rights when setting up the doc, and transferring or archiving a doc/space when it is moved or completed.

• Single source of truth. Establish rules for what is “canonical” to create a single source of truth.When information should be accessible from multiple places, link rather than duplicating pages.

• Discoverability is key. We need clear rules on what goes where and fewer, established entry points which act as indexes to linked docs.

• 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.

What goes where?

OEP-19 provides guidance on long-term developer documentation. Summarizing, with light edits:

...

• 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 or app and be linked from their respective repo/app-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.

are either Internal (private resources to edX e.g. IT, HR, Brand) or External (open to the Open edX community e.g.) and should be clear about their audience. Additionally, we think of spaces in 2 broad categories.

• Centralized Spaces are of broad interest across/outside the org so should be written to be understood by that broader audience. This includes spaces like:

  • Company internal resources (IT, HR, Facilities, Brand, etc.)

  • 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.resources (https://openedx.atlassian.net/wiki/spaces/AC

    Shared resource spaces (e.g.

    , UI toolkit)

• Localized Spaces - Used for specific teams/individuals, are for organizing focused projects/teams so are not meant to be shared/understand by those outside of the group the space is meant to serve. These include spaces like:

  • Team / squad / personal spaces

• See Proposal: Confluence Organization for more details on how we propose organizing spaces.

• Every space should have an owner .

  The owner should “watch” the entire space and is responsible for

  in charge of keeping the space clean, organized, and useful (including archiving of old pages if not granted to other editors).

• 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:

  #updates-needed

  tags proposed in Tags & Signaling.

Tags & Signaling

This is a set of proposed labels to apply to Confluence pages meant to signal the type of page or actions that should be taken on a page. Using searches or crawlers, space administrators could use these to keep spaces organized.

• #update-me - Propose adding this new tag to help space owners find out-of-date pages.

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

  .

• 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

Docs can be written in tools outside of Confluence or GitHub, but everything should be discoverable from one of those 2 tools.

For

...

in-progress docs (e.g. a Miro diagram), they should be linked to the related project/repo.

Info should be moved to Confluence/GitHub when complete in other authoring tools. Delete the old doc or replace the content with a link to the new page after the documentation has been moved.

• For permanent docs Graphical Tools (Miro/Figma) etc. - Extract finalized images into the new location (e.g. diagrams that can’t be done with other tools) they should be linked from a permanent home (Confluence/GitHub) Core Committers Phase 2 )

• Doc Tools - Extract the text or attach the rendered doc in the new location.

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