...
The Open edX project documents things in many places, including repos, RTDs, the wiki, the Open edX website. It’s messy, without a clear strategy for what types of docs should live where and why, and for whom docs are intended.
It’s not clear to end-users where to look for the right documentation to address their questions or to learn the platform. It’s also not clear to contributors where to put new documentation, or how to improve current documentation.
Information is often out of date.
httphttps://Docsdocs.edx.org is specific to http https://edx.org. With the split of edX from Open edX, it’s necessary to design a documentation strategy that speaks specifically to Open edX user needs, pain points and expectations, and that removes edX specific needs, pain points and expectations.
Documentation is less developed, or not organized in the most appropriate way, for certain types of users, for example faculty/course authors. One Instance administrator noted that some Open edX Documentation is actually a barrier of entry for faculty, rather than a facilitator to entry, because 1) the documentation is too dense; 2) there’s not a clear path through the documentation to connect the faculty with their need; 3) it’s overwhelm at first site.
...
Marketing materials would live on http https://openedx.org and would be geared towards introducing and “selling” the value of the platform. If content is specific to marketing it would probably live there but if we are doing introductions of our products, then they should probably be tutorials in the relevant persona’s space and the content can be cross-linked or embedded into our marketing site.
...
Much of the non-tech oriented documentation is too dense and difficult to navigate. Faculty/course authors/instructional designers/educators want “quick hit” documents that enable them to get a course up and running in under 10 minutes. This documentation doesn’t currently exist.
Developers’ main pain point is in navigating the messy documentation environment. A lot of good documentation exists, but they don’t know how to tap into it, where to start, or how to find what they need.
A challenge for all users is that many current documents conflate different types of documentation into one. For example, many RTDs are a mix of explainers/how-tos and references/”why”, and this conflation is one major reason why the documents are too dense and difficult to navigate.
The current main point of entry to search the documents, the free text search bar on http https://docs.edx.org/, doesn’t turn up targeted results.
...