First, a huge thanks to everyone who has submitted feedback, comments and ideas on tCRIL’s Documentation Restructuring Proposal. Your input has been highly valuable in helping us formulate next steps to advance the project to improve Open edX documentation.
Where we are today
We’ve created a central index/tree for all Open edX documentation here: Open edX Documentation — Latest Documentation documentation
We’ve decided to organize the documentation tree around key Open edX personas/users, namely:
- Educators/course authors
- Course operators
- Site Operators
We’ve identified four key types of documentation that each persona should have:
- Quick start
Here’s an example of what those four doc types look like for the Educator/Course Author persona: Open edX Educators — Latest Documentation documentation
What we’d like to do next
Before we create content itself (or repurpose it from current readthedocs), we’d like to create a comprehensive “table of contents” or “glossary” for each persona. In other words, let’s create a robust list of docs that each persona needs, in each document type. For example:
What are the how-tos a course author would need?
What are the reference docs an instructional designer would need?
What are the how-tos an extension developer would need?
Here is an example table of contents for Educator/Course Author how-tos (not complete): Educators: How-tos — Latest Documentation documentation
We’d like to invite the community to help us crowd-source these Tables of Contents. We’ll use this as the starting point for what content needs to be written and where we should focus future energy. Relatedly, are you interested in “owning” a persona, or a content type for a persona? Helping us build out the documentation for that persona and keeping it up to date? Don’t worry if you don’t have a lot of experience, we can help. Please reach out and we’ll set you up with everything you need to help us build out Docs 2.0.
Respond below, or reach out to Jenna (firstname.lastname@example.org) or Feanil (email@example.com) to learn more.
Hi @jmakowski , Shannon and I are in! I’ll connect with you via email and just let me know if there are any working sessions or meetings that you’d like us to participate in. Here we go!
I am interested in creating documentation. I can commit 5 Hours per day on this documentation.
Greetings! I am interested in participating. I am new to this forum, yet have done a deep dive at eduNEXT to explore Knowledge and documentation initiatives.
I’m Wanda and serve as the Knowledge Management Specialist at eduNEXT in Colombia. I’m an experienced educator and learner at heart.
To date, we have created a Knowledge Management Strategy and Action Plan at eduNEXT which incorporates best practices framework around knowledge gathering and sharing, and includes documentation best practices. In late June, we began our pilot program in the area of Service Delivery, which is made up of 6 iterative cycles (2-week sprints each) to assess and improve our internal and public documentation to enhance the customer experience. Thanks to your efforts, we were able to accelerate our activity by incorporating several elements from your new Open edX Documentation proposal, such as user personas, panels for quick navigation, tools etc. Thus, we adapted our User Roles to align with our documentation and with our eduNEXT Control Center (ECC) management console. We are excited to see the final outcomes. That said, we are at the same point in our endeavors. Identify core content for each role. So I was happy to see your invitation to contributor as it aligns perfectly to what we are doing and where we are in the planning and implementation of our project.
In July, I met Feanil and along with a few members of our team at eduNEXT, we discussed how we can collaborate to work through some of the documentation created and provide feedback. So, I’m looking forward to getting more involved in that as well.
Feel free to reach out and let me know how I can best be of assistance. Thanks.
Also, if you’d like more information about our pilot program for Knowledge and documentation, I’d be happy to connect with you.
I am Utku and am the lead developer for our instance at NYU Shanghai.
I have been working on our instance for the past year and have also been active in the forums (including the depreciated Tutor forum) by answering questions to the best of my ability.
My experience mostly covers the
Site Operators and
Developers personas and I would like to contribute to the documentation in these areas.
Hi @jmakowski I’m really excited about the work that’s happening around Open edX documentation. Should we be sharing topic suggestions in this thread, or through a different channel?
I’d also be interested in helping to build out documentation, if appropriate opportunities are available.
Thanks Parvin, great to hear! I’ll email you with more details.
Fantastic Wanda, we’ll be emailing shortly with more details.
Great Utku, expect an email shortly!
Thanks Michael! Will be in touch via email shortly.
Hi Jenna, I’m interested in participating / could bottom line a “2U developer” persona. I’m also really interested in gathering a set of developer personas more generally, I think it would be helpful as we think through things like public roadmaps and how to evolve our processes around BD and FC projects.
Hi Jenna - we spoke after the October session. I’m interested in Documentation of the /admin Django options - either collating or checking something that is an old/draft version.
I can’t be the only person who
- wants more control/options than “Studio > Advanced Settings”
- but who isn’t a developer, so can’t dive into Github /
Hello to all the respondees so far, and anyone new to this thread. I’d like to get a team going working on this. Specifically for the Educators persona, but happy to share any lessons learned with other personas.
To that end, I’ve mapped the current state of the Educators documentation (attached). It’s just a starting point but it teaches us some things immediately:
- There is a lot of “low-hanging” fruit for people interested in getting started with a simple documentation task.
- There is still a lot of room to shape the vision of what an educator needs to see in this documentation. Right now, we have a lot of how-to’s (but still more to go… this is Open edX after all) but are lighter on concepts and references.
Could folks re-affirm their interest in being involved in the “educators” persona? I will set up a quick intro before the edX conference just to go over the inventory and start talking about the tasks required for a group like this.
Educator_Documentation_Map_2023Mar.pdf (736.8 KB)
Trying again as an image so you don’t have to download a PDF
HI, I need some help regarding this issue.
I was able to run the docs locally and I’m supposed to make them appear under the https://docs.openedx.org/ as per the issue created by @feanil . Now what I need to understand is how the documentation is structured and how they are working altogether so I could then start working on adding the API docs. Thanks in advance.