Open edX® Educator's Docs UX/UI

Owned by John Swope
Last updated: Nov 01, 2024
4 min read

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:

  1. Django documentation | Django documentation

  2. Canvas Basics Guide

  3. Instructor Guide

  4. https://docs.jupyter.org/en/latest/

  5. Teacher Center | Google Classroom Training

Principles of Good Documentation UX/UI

  1. Include Quick “Getting Started” jumping off points for new users.

    1. https://docs.jupyter.org/en/latest/start/index.html

    2. Django documentation | Django documentation

    3. Teacher Center | Google Classroom Training

  2. Provide Task-Based Navigation

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

      1. https://research.utwente.nl/en/publications/what-makes-it-findable-an-exploration-on-user-search-behavior-and

      2. Excerpt (emphasis is mine):

        1. “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.

  3. Offer Clear, Actionable Language

    1. Google is a good example of clear, simple language that gets right to instruction: Teacher Center | Google Classroom Training

  4. Incorporate Feedback Loops

    1. Use call-to-actions to elicit feedback to learn how well your documents are supporting your audience.

    2. What are grading schemes?

 

Existing Structure

In our existing navigation structure, the hierarchy is as follows:

  • User Type

    • Diataxis Category

      • Task

        • Document (how-to, concept, reference, quickstart)

image-20241030-153237.png

That matches our folder hierarchy

E.g. educators/how-tos/share_course_social_media.rst is [user type]/[diataxis category]/[document]

image-20241030-153313.png

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)