Goal/focus of discovery project: tCRIL undertook a discovery initiative to learn more about pain points and challenges in the Open edX Documentation ecosystem. Barriers to documentation use and maintenance have been noted for years, but there has never been a comprehensive investigation into the full scope of the problem. This discovery initiative was intended to fully understand the scope, as well as make recommendations for an approach to address them.

Link to discovery ticket/epic: Open edX Documentation Restructure: Discovery · Issue #130 · openedx/platform-roadmap

Discovery findings/artifact: As a result of our discovery work, we have created a proposal with specific recommendations for re-structuring Open edX Documentation workflows. The entire proposal is copied below.

We welcome feedback and input on the proposal. Specifically, we have three questions/assumptions that we’d like to test:

Based on your experiences with Open edX Documentation:

Is our proposal to build a root RTD site as an index for all Open edX-related documentation the best approach for organization/discovery?
Is our proposal to create entry points and pathways by user personas (described below) the best approach to organize the root RTD site?
Is our proposal to use the documentation quadrant approach (described below) the best approach to create and present documentation going forward?

Please feel free to provide your input in the comments, or make in-line comments in the proposal directly. Alternatively, take our quick poll after reading!

Summary and Recommendation

Problem

Over the years of its existence, the documentation to support Open edX has grown and evolved organically. Without a clear end-to-end information strategy to guide the creation and organization of the documentation, and without a clear definition of users’ end goals, a number of problems have arisen:

The Open edX project documents things in many places, including repos, RTDs, the wiki, the Open edX website. It’s messy, without a clear strategy for what types of docs should live where and why, and for whom docs are intended.
It’s not clear to end-users where to look for the right documentation to address their questions or to learn the platform. It’s also not clear to contributors where to put new documentation, or how to improve current documentation.
Information is often out of date.
https://docs.edx.org is specific to https://edx.org. With the split of edX from Open edX, it’s necessary to design a documentation strategy that speaks specifically to Open edX user needs, pain points and expectations, and that removes edX specific needs, pain points and expectations.
Documentation is less developed, or not organized in the most appropriate way, for certain types of users, for example faculty/course authors. One Instance administrator noted that some Open edX Documentation is actually a barrier of entry for faculty, rather than a facilitator to entry, because 1) the documentation is too dense; 2) there’s not a clear path through the documentation to connect the faculty with their need; 3) it’s overwhelm at first site.

The above problems make it difficult for users to engage with the Open edX platform, whether they’re a software developer looking for documentation for new feature flags or a faculty member looking for instructions to quickly build a new course.

Discovery Summary

To better explore the possible solutions to the above problems, we undertook a series of discovery initiatives to help us better understand the following:

Who are the documents for?
What problems do they solve?

Based on the answers and insights we compiled in response to the above questions, we asked ourselves:

Where should the documentation live?
How can we best organize it to help get it to the right people at the right time?

To accomplish this, we did 3 things in parallel:

An audit of the current documentation in the Open edX organization
Community Interviews to establish baseline personas for our stakeholders
Best Practices research into how others in our field and beyond successfully organize information.

Detailed findings from our discovery work can be found below after the recommendations section.

Recommendations

Based on the discovery work summarized above, we make the following proposals:

1.We propose a root RTD site (docs.openedx.org, or similar).

The site will act as the root for all Open edX related documentation. Its goal is to make the organization of documentation clear and make it easy to find the right kind of information based on a user's needs. It is essentially an index that helps to orient users and wayfind to the right document for their needs.

2. We propose that the RTD site is organized by personas, such that each persona user has a clear entrypoint into the documents relevant to their needs. We suggest starting with the following, and expect this list to expand:

Site Operators: Set up/upgrade and run an Open edX instance
Educators: Build an Open edX course
Course Operators/Administrators: Run an Open edX course
Software Developers: Customize an Open edX course

3. We propose to organize the documentation for each persona around the documentation quadrant approach. Thus we will begin with the following four document types/categories:

Quickstart guides
How-tos
References
Explanation/Concepts

To demonstrate what these recommendations look like in action, we have created a beta template for the RTD root site. We have created basic, high-level outlines for the documentation journey for two sample personas, educators and developers.

We will also be working on a recommendation for how repo-specific documentation should be structured based on the same principles but that discovery work is still in progress.

Sample: Developer Documentation

Sample: Educator Documentation

Heuristics for Locating Documentation

We propose two “rules” to help answer the question: Where should a document live:

The core of docs.openedx.org will live in a single documentation project in the docs.openedx.org repository.
All documentation should live as close to the code that it is describing as possible. If some documentation spans multiple code bases, it should live in the root docs.openedx.org repo. We can imagine this is likely for certain Quickstarts and How-to guides that span multiple components.

Value and Impact

Fixing the problems noted above will have positive impacts for everyone who uses the Open edX platform:

It will support an increase in platform adoption by making it easier for developers and site operators to install and to upgrade.
It will support an increase in usage for non-tech oriented audiences.
It will make it easier for the open source community to contribute to document upkeep and maintenance, resulting in a more robust and self-sustaining ecosystem.

Discovery Findings: Work Done So Far

We undertook a few Discovery Milestones concurrently to better understand the problem and potential solutions. This is a summary of those discovery tasks.

Documentation Audit

First, we completed a full audit of all Open edX Documentation. This helped us to identify where various types of documentation lives and what audience it currently serves.

In summary, Open edX Documentation lives in:

ReadTheDocs
GitHub repos
Confluence Wiki Pages

Main types of Open edX Documentation include:

Explainers and references comprise much of the RTDs
Quickstarts and how-tos comprise much of the RTDs
ADRs - Explainers which are repo specific
OEPs - Explainers and reference

Persona Profile Exercise

Second, we conducted interviews with Open edX users to understand their pain points and challenges, and to build an informed strategy for how the right documentation, organized in the right way, can address those pain points. We distilled the results of these interviews into Persona Profiles.

As a result of the exercise, we learned that:

Much of the non-tech oriented documentation is too dense and difficult to navigate. Faculty/course authors/instructional designers/educators want “quick hit” documents that enable them to get a course up and running in under 10 minutes. This documentation doesn’t currently exist.
Developers’ main pain point is in navigating the messy documentation environment. A lot of good documentation exists, but they don’t know how to tap into it, where to start, or how to find what they need.
A challenge for all users is that many current documents conflate different types of documentation into one. For example, many RTDs are a mix of explainers/how-tos and references/”why”, and this conflation is one major reason why the documents are too dense and difficult to navigate.
The current main point of entry to search the documents, the free text search bar on https://docs.edx.org/, doesn’t turn up targeted results.

“Best Practices” Research

We conducted some research on best practices for organizing open source documentation. First, we looked at the Divio Approach. Secondly, we looked at the strengths of a similar open source project in the edtech space, Moodle. In general, we distilled the following best practices:

Document types should not be conflated. For example, a “how to” should not be mixed with a “concept” doc.
Documents should be targeted at clear personas/end users. A faculty quick start should be different from a software developer quick start, as they address different pain points and different needs.
Documentation should be organized at a high-level around an index.
The interface should be simple and there should be a clear journey through the documentation for each user type/ each persona.
Each persona should have a clear, simple set of “quick hit” documents as an entrypoint, such as quick start guides, how-to guides, tutorials. Then if they need to dive deeper, they should be able to find more complex references and guidance.

Open edX Product Management

Discovery/Proposal: Open edX Documentation Restructure