Rethinking Open edX Documentation

Owned by Kira Miller
Last updated: Apr 28, 2022
1 min read

Meta

Date: April 26, 2022 16:45 am UTC+1, Room -115

Presenters: Jenna Makowski • Feanil Patel

Main Questions

  • Who are the Open edX documents for?

  • What problems do they solve (and for whom?)

Personas

  • Understand needs/pain points w/ “Day in the Life” profiles

  • Interests, goals, motivations, challenges, and needs & expectation

  • Synthesizing the data to guide our decision

    • Short how-to guides for non-tech

    • Best practices for SME’s who aren’t pedagogy experts

    • Etc….

Audit

  • Documentation is everywhere (ReadTheDocs, Github repos, Confluence Wiki Pages)

  • Best Practice research

    • Looked into Season of Docs, Github, Moodle, and Django to see what they share

    • Quick-starts, How-to Guides, Explanation, Reference

Don’ts

  • Don’t conflate document types

  • Don’t conflate user personas

  • Don’t overwhelm readers

Do’s

  • Create clear, simple pathways (not everyone wants to know all the details)

  • Create “quick hit” entry points

  • Orient around common pain points

~* The Proposal *~

  • A root RTD index → organized by persona → documentation

  • Clear User Home pages (Educators, Course Operators, Developers, Site Operators, Documenters)

  • How-To Pages, pages to deep dive in, other separate pathways

  • Engineering GitHub

    • Split into decisions, concepts, quickstarts, how-tos, more_references, index

Q/A

  • Will the docs require PR reviews like others?

    • The more eyes we have on a thing the better it is, we are discussing the specifics

  • Is this specific to open edX, or is it also something for 2U/edX community

    • The research is really general, so I definitely think it can be applied on the 2U side

  • Will the research and proposal be public?

    • Yes! We will post it after this.