The highest-level goals for this doc are to:

• Propose a structure and linking for spaces in Confluence

• Propose templates / needed information for different types of pages

Resources:

• Spreadsheet of existing confluence spaces (and markup)

Context

Engineering themes/squads/teams currently organize themselves on the wiki in a lot of different ways which makes it difficult to discover information about other squads and hinders cross team communication and collaboration.

...

… documentation comes in all shapes and sizes, internal and external. Different types of docs require different voice, tone, formatting, contributors, audience, and content.

...

Organizational Proposals

1. All spaces have a clear owner (listed in the top-level doc whenever possible) to manage updates, permissions, and archiving.

2. We use 3 large “types” of documentation, designed for different purposes:

   1. Reference/system/end-user documentation - The documentation we’re most familiar with: docs that explain how to do something, or provide helpful reference.

   2. Team documentation - Landing pages for organizational groups of people, including contact information and links to docs/projects.

   3. Project documentation - Pages for organizing projects, particularly across-theme/org. These will act as source-of-truth and points of entry for finding out about a project.

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

   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.

Rationale:

• The highest level goals are organizational and doc clarity & helpfulness. Establishing clear owners helps make it clear who should be updating/making decisions about a doc.

• Using different documentation patterns for reference/team/projects allow us to scope documentation in a way we scope our thinking and organization in edX already, making it easier to navigate the org.

• We also need a way of pruning out of date info. Using tags helps space owners identify out of date pages, which we empower them to actively archive.

Organizational Proposals

1. Highest level space is edX which includes links to:

   The edX space operates as the highest level directory and has links to departments and theme spaces for discoverability.

2. Departments & Functions - Departments and functions each get their own space. They contain docs that are helpful across team/theme/org boundaries (e.g. Brand, UX, HR, Data Engineering) like reference, end-user docs, and projects scoped to the department (e.g. brand guidelines, HR reference, architecture docs).

   Internal / External - Some

   Note that some of these spaces (e.g. Brand, Engineering) should inherently be public, while others (e.g. HR, IT, Eng-internal) should be internal only. Spaces should clearly identify the audience, in the space title or landing page and have access rights set accordingly.

3. Themes - Themes also each get their own space, linked from the edX space for visibility. They are a cross-functional organization of resources around a theme (e.g. Content, Engagement).

   Themes further contain:

4. Teams - An entrypoint for finding teams connected to a theme. This could be a folder of team pages or a link to team spaces, depending on team setup. See #Teams header for more.

Projects - A folder for projects that are owned by the Theme and span multiple Teams, this allows for pages to be accessible & discoverable by the entire theme and allow for teams/resources to transition on/off the project

1. Themes should link to the teams on a theme for discoverability.

2. Projects may also be created as pages on a theme level for cross-team (but theme-internal) projects.

5. Teams - Teams get their own spaces for internal documentation and collaboration. Internally they may do what they please but should be linked from the owning theme and have some basic external-facing info (see further down the page in Teams to see what should be in a team space).

6. Projects - Projects of sufficient complexity should be entered into Confluence, establishing a landing page for schedules/docs/decisions. They may either get their own spaces or be a page/folder under a specific Team/Theme, whichever is the appropriate owner or provides appropriate access rights.

7. Working Groups - Groups or initiatives that don’t have clear functional or theme owners (e.g. Security Working Group, DEI, Hackathon). Like projects, they may chose to create their own spaces or exist as a page tree under an appropriate owner (probably edX, except for function-specific groups like Security Working Group).

Rationale -

• Having a highest-level space act as a directory makes other parts of the org discoverable. Structuring our docs like we structure our organization helps enforce mental models that make traversing the docs (and org) easier.

• Continuing to use department/function spaces allows functional docs (e.g. engineering, HR) to be broadly accessible across the org but and to control internal/external access.

• Themes are the construct we already use for project and team planning, so creating spaces for Themes helps match that scoping appropriately.

• Teams should be granted flexibility to organize as they want. To avoid overhead, they can exist only as a sub-page of a theme, or operate their own space. This also allows for a team to persist docs (e.g. retros, internal reference) across org changes. Regardless, teams should be discoverable in the Theme under which they operateDocs and access rights are most commonly scoped to a space. Allowing for the creation of more spaces allows individual teams/projects/themes to internally organize in the best way for them.

• Use of linking allows for discovery of disconnected spaces.

• Providing “external” info on each project/team allows for outside project/team members to understand how to interact with or contact the project/team.

Sample Doc Hierarchy

Example hierarchy, elements map. Highest-level bullets are spaces. Sub bullets are pages/folders. Elements in brackets are placeholders for actual themes/teams/projects.

• edX

  • Departments & Functions → Links to ENG, IT, HR, etc

    .Projects, reference, and end-user documentation related to the function

    .

  • Working Groups →links to Hackathon, DEI, etc.

  • Themes

  • [ Theme A ]

    • Teams

      • [ Team 1 ]

        • Projects > [ Project 1 ]

        • Projects > [ Project 2 ]

      • [ Team 2 ]

      • [ Team 3, etc. ]

    • Projects

      • [ X-functional project 1 ]

      • [ X-functional project 2 ]

  • [ Theme B ]

  [ Theme C, etc.

  → links to Content, Engagement, etc.

• [ Department - e.g. ENG ]

  • Reference docs & folders as appropriate

• [ Theme - e.g. Content ]

  • Teams → links to team spaces, e.g. [ Team 1 ], [ Team 2 ]

  • Projects → link to project spaces

• [ Team - e.g. Aurora ]

  • Projects → pages or links to pages the team owns

• [ Project - e.g. Enhanced Staff Grader ]

Teams / Working Groups

Team pages are used for organizing groups of people (this applies both to teams/squads and working groups). Their landing page (e.g. /wiki/spaces/PT/pages/1054113880 ) is used for outside-team members to learn about and contact the team. Internally, they may structure their docs however they like, following previously documented guidance for docs that have a broader audience. The template of required fields:

1. Membership - Who is on the team?

2. Past names - What are past names for the team?

3. Contact info - How does the team preferred to be contacted by people outside their team?

4. Docs - Where does the team store in-progress or other internal documentation?

5. Links - Utilize page bookmarks for helpful links like retro boards, slack channels, Jira board.

Rationale - Particularly with lots of team/org changes, tracking who is where, who owns what, and how to contact them have been repeated refrains. By clearly indicating who is on teams, what the team used to be called, and how to contact, we remove having to have a mental model of how the org has evolved.

...