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)

• Confluence’s own page on how to write better documentation

Organizational Proposals

Confluence is currently hard to navigate. There are relatively few spaces, each with a lot of nested information without a clear information hierarchy. How can we improve this?

High-level proposals include:

• Creating spaces for organizational groups. These exist separately from functional spaces (e.g. Engineering), which are largely disconnected with organization structure.

• Establish well-known directories, like the edX or Theme spaces which link out to team/project spaces.

• Embracing linking to improve discoverability and reduce duplication.

• Appointing space owners and empowering them to organize, upkeep, and archive docs within their spaces.

Spaces

What does this look like in practice?

1. The edX space operates as a directory that links to departments, themes, and company-wide resources (like work-from-home guidance).

2. Departments & Functions - Departments and functions each get their own space (this is already largely in place). These spaces contain reference 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).

   1. Note that some of these spaces should be public (e.g. Architecture & Engineering), while others should be internal only (e.g. HR, IT).

   2. Some functions may need both a public and private facing component (e.g. Security, Engineering). This should be accomplished with separate spaces which clearly identify the audience 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 act as directories for teams and projects within their scope.

4. 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).

5. Projects - Projects that cross team/theme boundaries should get their own space or page in Confluence (depending on scoping) as a way of organizing resources across the org. These should be used as a directory for schedules, docs, and decisions as well as listing the final decision maker to reduce ambiguity on a project.

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

• Structuring our docs like we structure our organization helps enforce mental models that make traversing the docs (and org) easier.

• Establishing well-known “directory spaces” (edX, themes) makes it easier to find and navigate spaces within the org.

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

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

What happens when Org/Team/Project structure changes?

TL;DR - doc/space owners are responsible for updating to reflect changes.

See Documentation Strategy for further notes/guidance.

Sample Doc Hierarchy

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

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

  • Themes → 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. https://openedx.atlassian.net/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.

Projects

Project pages/spaces are for centralizing information about a project while it is in progress. They should be viewed as the main directory for project discovery, planning, and working docs. Note: Technical decisions, when finalized, should still move to GitHub as noted in our Documentation Strategy.

Projects may be their own space, or exist as a pages under a team/theme, depending on what is the most useful for organizing resources. Regardless, project pages should answer the following:

1. Problem definition/summary - What is the project trying to accomplish?

2. Status - Where in the project lifecycle is this project (e.g. planning, implementation, delivered, abandoned)?

3. Membership:

   1. Who (individuals or teams) is working on the project?

   2. Who has the final say on project decisions?

4. Doc links - Relevant links to Jira epics/features, design/discovery docs, planning notes, etc.

Changing locations

Projects can change team/squad/theme. When they do, the docs should change location to be under the new owner’s space to give them access ownership and ability to move forward the docs.

Projects that do change locations should note (in the status or membership) the trail of moved teams for traceability.

Rationale - A consistent issue with collaboration/communication is having a clear, centralized location for docs and decisions. Teams are small enough where they might be able to keep it all “in their heads” but, for cross-team projects, we need better ways of organizing multiple minds. This removes the difficulty with discovering different docs and worrying whether they’re out of date. Identifying the key decision maker also removes the ambiguity of wondering who has the final say on a design decision.