(UXW) Update our documentation for Oppia users and lesson creators

[seanlip]

Platform
Oppia Web

Describe the request

We have some documentation for users at:

• oppia.github.io (source: https://github.com/oppia/oppia.github.io)
• https://oppia-user-guide.readthedocs.io/en/latest/ (source: https://github.com/oppia/creator-documentation)

The former is very old and hasn't been updated in years. The latter was created while the corresponding functionality was still in the process of being implemented, and was never released formally; it is also a bit out of date.

It would be nice to take a pass on these, and:

• Update anything that needs to be updated (including images/videos)
• Consider the information architecture -- should we consolidate the two in one place?
• How do users find out about this documentation -- what are the entry points?
• Publish the documentation for the benefit of Oppia users and lesson creators

This is purely a UXW (not UXD) project, though it may be worth collaborating with UXD on the entry points to the documentation from the website.

UXR success criteria*

• Parents/Teachers can use the website without issues.
• Lesson creators can use the website without issues.

DESIGN APPROVAL CHECKLIST -- DO NOT EDIT.

• UX Design approved (Android mocks should include dark mode)
• UX Writing approved
• Product approved

For a design project to be completed, it needs approval from UXD, UXW and PM. Please tag the following reviewers when your project is ready (at least one reviewer for each of the bullet points below):

• UXD: @rflore / @S4v8n (for Web projects), @seanlip (for Android projects)
• UXW: @tamiorendain
• PM: @seanlip

[davishedrick]

@seanlip I have a couple questions about this project.

1. After taking a deep dive into the content, the second link (the user guide) is the only link that I've found that provides text that I can edit properly. The other seems to be just code along with text. For someone who has no coding experience its hard for me to view the proper information architecture and to properly determine whether content needs to be updated. This could just be an issue with how I am viewing the content, but would enjoy your insight into how you see me using the first and third links.

2. What kind of "updates" are you suggesting. Are you suggesting I pore over the content to verify its accuracy and updates with how the platform operates? If so, It would take incredibly long to verify each sentence is wholly accurate across the current Oppia platform. This would be especially tedious considering I don't have access to certain pages as I am not a contributor or translator for lessons. Not sure I'm the right person, if that's the ask.

3. Is there a reason lessons are referred to in the home page and on the side ("Lesson creators," "Create a lesson") but are referred to as explorations in both the key terms page and in the Lesson creators section? Aren't they the same thing?

What I can do is take a look at the user guide, and update information architecture issues, grammar, punctuation, brand voice as well as update any content that I can find that is not how the current platform is laid out. This will not guarantee 100% accuracy.

If there's anything else you are looking for for this project besides what I laid out in the paragraph before, let me know. Thanks.

[seanlip]

Hi @davishedrick, sorry, the first item wasn't linked properly for some reason. The actual link to look at is https://oppia.github.io/#/ -- does that help? You don't need to look at either of the "source" links, they are just there for reference.

Also, lessons and explorations are the same thing, and it would make sense to standardize the terminology across the site/docs. Thanks for picking up on that!

Re "updates", that's a good question. I'd be happy to give you (and anyone else on the UXW team who's working on this issue) access to a test server where you can have all the permissions needed to explore the relevant flows. Also, I agree this is a largish project and it might be better to split this issue into sub-parts that multiple UXW team members can work on in parallel. Would this help address the concerns? Ultimately, the goal is for the documentation to match the platform (which is why accuracy is important) and also be presented in a way that is effective for our end users and contributors to use as a reference (so IA, grammar, punctuation, brand voice etc. are all good things to look at as well).

Please let me know what you think about the above, and I'm also happy to answer any further questions. Thanks!

[davishedrick]

@seanlip Apologies for the late response. Ok great. Yes, a test server would be useful here and splitting it up into sub-projects would help too. I know Aparna has been itching for more projects to work on. It might be a great way for us to work in tandem. Let me know how you would like to split up the task and in the meantime ill still keep working at the user documentation.

[davishedrick]

@seanlip Actually as I see it, there are two main parts to this project.

One is labeling all the information the user guide and the user documentation as redundant, relevant, needs to be updated, or needs to be deleted.

Two is going through and updating all the information that needs to be updated in one place and on one document with the help of your test server.

I'm happy to start on the first portion, then I'll try and recruit another writer to help me go through the second. We can then divide the project into the pages that need to be updated, adjusted, or deleted. If you have another idea, let me know.

[seanlip]

Hi @davishedrick -- thanks! I don't have a strong opinion on how to break things down, and the approach that you suggest sounds good to me, so please go ahead :)

I have also sent instructions separately to get you access to the test server.

[davishedrick]

For visibility, here's the document we will be working out of to deliver the user documentation:

https://docs.google.com/document/d/17h5ZakHlqAmsjeDCPMqdPIP7bEB5j76jGLJk1gAsM9k/edit?tab=t.v0exxu1z6qro