diff --git a/source/_figures/reference/tutorial-ratings-01.png b/source/_figures/reference/tutorial-ratings-01.png new file mode 100644 index 00000000..fb699ce0 Binary files /dev/null and b/source/_figures/reference/tutorial-ratings-01.png differ diff --git a/source/collaboration/collaboration.rst b/source/collaboration/collaboration.rst index b758a3f2..76098f24 100644 --- a/source/collaboration/collaboration.rst +++ b/source/collaboration/collaboration.rst @@ -41,7 +41,7 @@ Contribution guidelines *********************** The |CL| documentation is written using reStructuredText. Use our guidelines -and best practices to write consistent, readable documentation. +and best practices to write consistent, readable documentation. If you're writing a tutorial, review our skill levels to better target a user group. .. toctree:: :maxdepth: 1 diff --git a/source/reference/index.rst b/source/reference/index.rst index 12f2ec71..a498527b 100644 --- a/source/reference/index.rst +++ b/source/reference/index.rst @@ -13,4 +13,5 @@ features. bundles/bundles system-requirements image-types - man-pages \ No newline at end of file + man-pages + tutorial-ratings diff --git a/source/reference/tutorial-ratings.rst b/source/reference/tutorial-ratings.rst new file mode 100644 index 00000000..dfed2cc5 --- /dev/null +++ b/source/reference/tutorial-ratings.rst @@ -0,0 +1,52 @@ +.. _tutorial-ratings: + +Tutorial difficulty ratings +########################### + +Tutorial difficulty ratings provide a simple way to start using and developing with |CL-ATTR|. If you're new to the distro, we suggest starting with ``Easy`` tutorials and working towards the more ``Difficult``. Ratings not only expose learning paths but also provide a starting point from which to advance or improve use cases, so be sure to :ref:`share your insights `. Three main metrics help us to determine how to rate a tutorial: + +.. contents:: + :local: + :depth: 1 + +The sum total of these metrics, the rating shown in Figure 1, represents the +ability to successfully complete a tutorial based on skill level, balanced against the risk of failure. + +.. figure:: /_figures/reference/tutorial-ratings-01.png + :scale: 100% + :alt: Tutorial difficulty ratings + + Figure 1: Tutorial difficulty ratings + +Time and complexity +******************* + +Are there about 8 or more *complex* steps? *Complex steps* are those that: + +* Require more than one action +* Require external reading/review +* Include explanation or context +* Give alternative(s) + +This metric factors in the cognitive load and its impact on a user. + +User experience level +********************* + +Our tutorials primarily target two types of Linux users. + +**Experienced** A Linux\* user who is familiar with common topics like userspace, networking, sudo privileges, services, and more. + +**Advanced** A Linux user who is beyond Experienced and is familiar with most sysadmin and programming topics. + +This metric establishes a starting point for skills, based on user +experience. + +Impact of failure +****************** + +The impact of failure calculates the risk of failing to complete a tutorial as a result of entering incorrect data or configuration, or failing to follow the steps in the given order. We estimate the potential state of a system, given these failure scenarios and their severity. This metric also factors in the ability to troubleshoot and recover when faced with errors. Therefore, the final impact incorporates the previous two metrics while it helps to predict an appropriate difficulty rating. + +* Will impact of errors be inconsequential? ``Easy`` +* Will impact of errors cause inconvenience (but system still works)? ``Moderate`` +* Will impact of errors cause system failure (difficult to recover)? ``Difficult`` diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index 90ab15b8..3d579398 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -3,8 +3,8 @@ Tutorials ######### -Explore our tutorials to discover what you can do with |CL|! Now conveniently -sorted by difficulty level! +Explore our tutorials to discover what you can do with |CL|, conveniently +sorted by difficulty level! Learn about :ref:`how we evaluate tutorials `. .. container:: multicolumns