add Recipes section under Guides category

_redirects

@@ -17,3 +17,8 @@
 /contributing/writing-style /contributing/style-guide 301
 /tutorials/nixos/build-and-deploy/* /tutorials/nixos/:splat 301
 /tutorials/first-steps/declarative-and-reproducible-developer-environments /tutorials/first-steps/declarative-shell 301
+/recipes/best-practices /guides/best-practices 301
+/recipes/troubleshooting /guides/troubleshooting 301
+/recipes/faq /guides/faq 301
+/recipes/python-environment /guides/recipes/python-environment 301
+/recipes/direnv /guides/recipes/direnv 301

source/contributing/documentation/diataxis.md

@@ -3,7 +3,7 @@
 We aim to build our documentation according to the [Diátaxis framework for technical documentation](https://diataxis.fr), which divides documentation into four categories:
 
 - [Tutorials](#tutorials)
-- [Recipes](#recipes)
+- [Guides](#guides)
 - [Reference](#reference)
 - [Concept](#concepts)
 
@@ -25,12 +25,12 @@ While the activity itself is important, the goal is also to connect the dots bet
 
 The structure of tutorials should minimise the cognitive load on learners, and actively avoid choices and opportunities for user errors.
 
-## Recipes
+## Guides
 
-Recipes are a list of steps showing how to achieve a specific goal or solve a specific problem.
+Guides are a list of steps showing how to achieve a specific goal or solve a specific problem.
 The goal is to help the reader reach a specific end, not understand the underlying theory or broader context.
 
-A recipe assumes that the reader already has the background to understand the topic at hand and therefore doesn't need to explain the introduction of each new concept.
+A guide assumes that the reader already has the background to understand the topic at hand and therefore doesn't need to explain the introduction of each new concept.
 
 ## Concepts
 
@@ -39,13 +39,13 @@ A concept can also describe the historical context behind why something works th
 
 If you find yourself wanting to write about the nitty gritty details of how something works, you most likely want to write an explanation.
 
-### Recipes vs. Tutorials
+### Guide vs. Tutorials
 
-We find that contributors primarily struggle with the difference between a Recipe and a Tutorial.
+We find that contributors primarily struggle with the difference between a Guide and a Tutorial.
 
 Here are several explanations to help you understand the difference.
 
-- A recipe is used in a "working" context where the reader just wants a sequence of instructions to achieve an outcome.
+- A guide is used in a "working" context where the reader just wants a sequence of instructions to achieve an outcome.
   - In this context the reader may already know or may not care how or why these instructions work, they just want to know what to do in order to achieve the desired result.
 - A tutorial is used in a "learning" context where the reader is following a sequence of instructions to gain practice performing a certain task.
   - Some small bits of motivation or explanation are helpful in this context to help a reader connect the dots with other things they may have already learned, but the focus is on the activity, not on _how_ or _why_.
@@ -55,14 +55,14 @@ A helpful analogy is landing an airplane in two different contexts.
 Let's say the pilot is unconscious and you now have to land the plane to avoid a crash landing.
 In this context you just want to know how not to die.
 You don't care about how or why, you just want to be on the ground in one piece.
-This is the context for a recipe.
+This is the context for a guide.
 
 A pilot training in a flight simulator wants to practice landing the plane.
 The pilot-in-training needs practice knowing when to deploy the landing gear, when to adjust flaps, etc.
 Actually landing the plane during the flight simulation is less important than learning the individual skills that make up a successful landing.
 This is the context for a tutorial.
 
-Finally, one last way of thinking about the difference between How-to/Recipe and Tutorial is like this:
-- Recipe: "step 1: do this, step 2: do that, etc"
+Finally, one last way of thinking about the difference between How-to Guide and Tutorial is like this:
+- Guide: "step 1: do this, step 2: do that, etc"
 - Tutorial: "take my hand as I show you how to do this"
 

source/recipes/index.md → source/guides/index.md

@@ -1,4 +1,4 @@
-(recipes)=
+(guides)=
 # Recipes
 
 These sections contains guides to getting things done.
@@ -7,10 +7,8 @@ These sections contains guides to getting things done.
 :glob:
 :maxdepth: 2
 
+./recipes/index.md
 ./best-practices.md
-./faq.md
-../templates/*
-./python-environment.md
 ./troubleshooting.md
-./direnv.md
+./faq.md
 ```

source/recipes/direnv.md → source/guides/recipes/direnv.md

@@ -1,4 +1,4 @@
-(direnv)=
+(automatic-direnv)=
 # Automatic environment activation with `direnv`
 
 Instead of manually activating the environment for each project, you can reload a [declarative shell](declarative-reproducible-envs) every time you enter the project's directory or change the `shell.nix` inside it.

source/guides/recipes/index.md

@@ -0,0 +1,9 @@
+(recipes)=
+# Recipes
+
+```{toctree}
+:maxdepth: 1
+
+Automatic environments <./direnv.md>
+Python development environment <./python-environment.md>
+```

source/recipes/python-environment.md → source/guides/recipes/python-environment.md

@@ -1,3 +1,4 @@
+(python-dev-environment)=
 # Setting up a Python development environment
 
 In this example you will build a Python web application using the Flask web framework as an exercise.

source/index.md

@@ -22,8 +22,8 @@ If you're new here, {ref}`install Nix <install-nix>` and begin your journey with
 Series of lessons to get started
 :::
 
-:::{grid-item-card} Recipes
-:link: recipes
+:::{grid-item-card} Guides
+:link: guides
 :link-type: ref
 :text-align: center
 
@@ -73,7 +73,7 @@ The following illustrate of what can be achieved with the Nix ecosystem:
 
 install-nix.md
 tutorials/index.md
-recipes/index.md
+guides/index.md
 reference/index.md
 concepts/index.md
 contributing/index.md