Open edX® Educator's Docs UX/UI
- John Swope
Goal
The goal of this document is to define the requirements and rationale for a friendly UX/UI experience for the Open edX Educators docs at https://dev.rheumnow.com/video-poster/zoster-vaccine-immunogenicity-jaki-treatment
We have recently completed a migration of legacy edX.org ReadtheDocs into Open edX Docs, so now our Open edX docs contains all the content that existed in edX.org, but we have a chance now to think about the user experience of the educator who is exploring documentation for Open edX specifically.
Context & Background
A migration from legacy edX.org ReadtheDocs to Open edX Docs was recently completed.
Open edX® LMS should provide user-friendly, helpful documentation to all users but especially new users who are learning more about the platform and how to use it.
A funded contribution kicked off in late 2024 to improve the Open edX Educator docs, which can then act as a template for other personas.
Inspiration
Examples of established sites with documentation, some of whom also use diataxis framework:
Principles of Good Documentation UX/UI
Include Quick “Getting Started” jumping off points for new users.
Provide Task-Based Navigation
Task-based hierarchies like Setting Up a Class, Grading Assignments, and Engaging Students help educators find the documentation for their need quickly without needing to understand the underlying system in-depth.
Excerpt (emphasis is mine):
“In our work, we find that participants’ subjective ideas on document findability correlate with their behavioral data to a large extent, as stated in section 5. In such cases, user behavioral data could be used to infer the perceived findability scores of online documentations. This finding provides new perspectives on redesigning online help centers. To put it differently, if we could build a prediction model out of large amounts of user behavioral data, we would locate some of the hard-to-find documents on our help centers, and then try to improve its design by examining user paths.
Offer Clear, Actionable Language
Google is a good example of clear, simple language that gets right to instruction: https://edu.google.com/intl/ALL_us/for-educators/product-guides/classroom/?modal_active=none
Incorporate Feedback Loops
Use call-to-actions to elicit feedback to learn how well your documents are supporting your audience.
Existing Structure
In our existing navigation structure, the hierarchy is as follows:
User Type
Diataxis Category
Task
Document (how-to, concept, reference, quickstart)
That matches our folder hierarchy
E.g. educators/how-tos/share_course_social_media.rst is [user type]/[diataxis category]/[document]
Note that task is not part of the folder hierarchy but defined within the category page.
Proposed Structure
Based on the principle of task-based navigation, I propose the following hierarchy. Note that this hierarchy is fully compatible with diataxis and better matches the documentation from other organizations that also use diataxis:
User Type
Behavioral Category
Task/Feature
Document (how-to, concept, reference, quickstart)
This can be done without modifying the underlying folder structure. But for consistency, maintainability, and readability, it is recommended to change the folder structure to match the UX navigation.
An added benefit of this structure is it is sensible for development and testing teams who develop and test features, so it makes sense to group their documentation in a single feature folder.
In this system, behavior category is not part of the folder hierarchy but defined in special Table of Content navigation files:
This is an important feature because, commonly, tasks/features are part of multiple behavior categories. e.g. “certificates” or “video” are often needed across topics (e.g. Setting up a course, Data & Analytics, Accessibility)