Documentation Content Types
Documentation Content Types#
To keep documentation streamlined and make it easy for users to find answers, we make each topic one of three types:
Quickstart topics may seem similar to How-Tos but have a different focus. Tutorials are specifically built for beginners and are meant to help them gain experience with the product. For example taking a course through the entire course lifecycle, even if there is no content, and it’s not excatly how you would do it with a real course, gives a beginner a meaningful experience that helps them better navigate the product.
How-to topics provide direct and easy-to-follow instructions to accomplish specific goals. For example, topics provide the steps to create a new course subsection and to schedule a course.
Reference topics provide details about a function or feature of Open edX. For example there are many details about course subsections such as the different publication states, grading configuration, and visibility that are not included in the how-to topic Create a Subsection but are fully described in the reference topic Course Subsections. These two topics are linked in See Also sections.
Concept topics provide best practices or other guidelines for using Open edX. For example, the topics Crafting Effective Learning Objectives and Aligning End-of-Module Assessments to Learning Objectives are meant to provide guidelines for educators.
When you are creating new documentation, you should identify which type(s) of topics you need to create.
For more details on these topics check out the the The Diátaxis framework which we use as our guiding framework for building these docs.