Merge Tutorials and How-to Guides

[mjherzog]

We do not need separate top-level sections for Basic Tutorials and How-to Guides (esp. clear since most of the Basic Tutorials subsections are titled "How to....".
We should merge all of the content for these two sections under How-to Guides with "How to Add a New License" and "How to Add New License Rules after.." after "How to set what will be detected..".
"Add a Post-Scan Plugin" will be the last entry in How-to Guides.
We should also remove "How to " from the subsection titles since that will be covered by the Section title.
In the future we may want to separate the more technical How to sections like Add a License or Add a Post-Scan Plugin from the rest, but that is not necessary with the current amount of How-to content

[AyanSinhaMahapatra]

@chinyeungli @mjherzog I am inclined to have tutorials and how-to documentation pages separately as this is different to me. I missed this issue earlier, or I would have commented before there was PR, apologies for the inconveniences.

When these were created we followed the https://diataxis.fr/ documentation guidelines (@DennisClark showed me this, and I like this concept very much), and even though these two sections are similar the key difference is:

1. Tutorials are very basic level and these help you get started with something, often hand-holding you through examples that is easy to follow through. This does not have all the details but might reference to it. Essentially these are what you follow when you are a new user, and going through all the tutorials should be easy enough and low-barrier for a beginner to complete and have a good overview of the tool.
2. How-To documentation is usually more advanced than basic tutorials and this tells you how to do one specific thing in a lot of details.

This is True even though most of our tutorials are titled "How-Tos", we can rename these pages to remove the How-To if this is a source of confusion. We could also explain the above points in the start of those index pages for the sections if that helps.

Also this page: https://scancode-toolkit.readthedocs.io/en/stable/tutorials/how_to_add_a_post_scan_plugin.html is more a How_to documentation and not a Tutorial as this is a bit advanced and explains how to achieve one specific thing.

[mjherzog]

@AyanSinhaMahapatra Thank you for bringing this issue back to life. I am not sure that we really have much documentation that fits the Tutorials category as defined in the diataxis framework where the lesson context probably requires that we provide more general information like what is SCA, why do you need it and then walk the user through an example of using SCA to solve a problem. For diataxis Tutorials are very different from How Tos.
For example on the SCIO RTD site all of the items listed under TUTORIALS are really HowTo.
For the near future I think that we should:

• Drop the Tutorials section from our RTD doc pages (until we actually have this type of content)
• Use the Getting Started section as a substitute for Tutorials for the near-term / medium-term
• Use the How-To Guide section for our current content - we should think of these as chapters in a Guide (singular) to be assembled over time (an example we could aspire to: https://cyclonedx.org/guides/OWASP_CycloneDX-Authoritative-Guide-to-SBOM-en.pdf)

More specifically for SCTK this means:

• Move Command Line Interface Reference to the Reference Section
• Move Plugins to the Reference Section
• Move the Basic Tutorials content to How-To Guide
• Eliminate the Miscellaneous section
  • Move Support to Getting Started (we do this for other projects)
  • Move Versioning Approach to Reference
  • Remove the Runtime Performance Reports - this is clearly obsolete
  • Remove FAQs and add relevant content to Getting Started (most of our RTD sites have something like Why ScanCode? and the rest of the FAQ content is dated.
• We may decide to add a standard FAQ section to our doc framework in the future.