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.