Re-org for images

content/2024-08-03-documentation-best-practices.md → content/documentation-best-practices/index.md

@@ -36,7 +36,7 @@ why a behaviour or a pattern exists, future maintainers might be tempted to drop
 Not all types of documentation have the same life cycle. Different pieces of documentation are more or less stable, and this determines
 which can act as a conceptual and theoretical foundation for your project.
 
-Examples of stable documentation include:
+#### Stable documentation
 
 * A README without code
 * A vision statement
@@ -45,8 +45,7 @@ Examples of stable documentation include:
 These ought not to change much, because they describe the basic problems that your code aims to address, solve or support in the long run.
 While it is normal to fiddle around with the boundaries of your project at the beginning, in general these should change infrequently.
 
-Some other documentation is called volatile, like:
-
+#### Volatile documentation
 * Documentation generated at runtime
 * Code examples
 * Tests
@@ -61,18 +60,38 @@ your project.
 > -- Cyrille Martraire, Living Documentation, 2019
 
 
-As such, here is a simplified model of the documentation cascade for a typical Haskell project, from the most volatile to the most stable
+#### Documentation cascade
+
+Here is a simplified model of the documentation cascade for a typical Haskell project, from the most volatile to the most stable
 sources:
 
+<img src="images/flow-of-documentation.png" alt="flow of documentation" width=70%>
+
+<details><summary>Code for this diagram</summary>
+
+```mermaid
+flowchart TD
+  A[Docs of your project]
+  B[Architecture document]
+  C[Official specs for your domain]
+  D["Docs of a core library (base, text, containers, etc)"]
+  E[GHC Manual]
+  F[Official specs for what the core libraries provide]
+  G[Papers]
+
+  A --> B
+  A --> D 
+  A --> C
+
+  D --> E
+  D --> F 
+  D --> G
 ```
-Haddocks of your library or a third-party library
-├──> Official specs for your domain
-├──> Architecture Document
-└─┬> Haddocks of a core library (base, text, vector, etc)
-  ├──> GHC Manual
-  ├──> Official specs for what the core libs provide
-  └──> Papers (without paywalls)
-```
+</details>
+
+> The Haddocks of your library or a third-party library have a dependency on the official specs for the domain, on an architecture document,
+> and on haddocks from the core libraries (`base`, `text`, `containers`, etc.).
+> The haddocks of these core libraries depend on the GHC manual, official specs for their own domain, and papers.
 
 Keep in mind that while the Haddocks of a project can refer to the project specs, or to an architecture document, these documents should
 never refer to the project's current implementation. If you must refer to the code, point to where it's located.
@@ -91,31 +110,34 @@ The [Haddocks for the `Set` datatype](https://hackage.haskell.org/package/contai
 (from the `containers` library) are an example of documentation which follows this model well:
 
 * They point to an overview of the API ([here](https://haskell-containers.readthedocs.io/en/latest/set.html): _volatile_)
-* They refer to the papers that have informed the design of its implementation: the absence of working links may be annoying,
-but the references can still be followed (_stable_)
+* They refer to the papers that have informed the design of its implementation (_stable_)
 
 ### Understand for whom you write
 
-This section introduces the Diátaxis Framework for documentation:
+It is of utmost importance that documentation answers the needs of the users, and for that we must understand these needs.
+Users need specific kinds of documentation depending on the situation they are in.
 
-<img src="https://diataxis.fr/_images/diataxis.png" width=100%>
+A common framework used for the classification of documentation is the Diátaxis Framework. It defines four types of documentation
+where each are a combination of _Acquisition_ or _Application_, and _Action_ or _Cognition_.
 
-> -- Diátaxis Framework, by Daniele Procida, https://diataxis.fr
+If a new user in need of actively acquiring some practice with the project, they can safely be pointed to the "Tutorials" part
+of your documentation: it is the part that focuses on "_Acquisition_" of knowledge through "_Action_".
+The focus of the tutorial is to make a prospective user acquire basic competence in handling the software: It is an ice-breaker.
 
+However someone who is in need of a deeper – but perhaps less immediately applicable understanding of the project –
+will be better served by the Explanation, which serves the need for thought (or _Cognition_)
 
-Diátaxis maps out the entire life cycle of one’s interaction with a system. Each of its four quadrants describes a different
-situation in which a user may find themselves.
+Here is the quadrant:
 
+<img src="https://diataxis.fr/_images/diataxis.png" width=100%>
 
-Diátaxis is not just about filling out all the quadrants like a checklist (although they are all good to have!).
-Instead, it is about understanding how each section focusses on a particular combination of user needs and situations.
-If a new user in need of actively acquiring some practice with the project, they can safely be pointed to the "Tutorials" part
-of your documentation, as it is the part that focuses on "_Acquisition_" of knowledge through "_Action_".
-The focus of the tutorial is to make a prospective user acquire basic competence in handling the software. It is an ice-breaker.
+> -- Diátaxis Framework, by Daniele Procida, https://diataxis.fr
 
-However someone who is in need of a deeper – but perhaps less immediately applicable understanding of the project –
-will be better served by the Explanation, which serves the need for thought (or _Cognition_)
 
+Diátaxis maps out the entire life cycle of one’s interaction with a system.
+
+But is not just about filling out all the quadrants like a checklist (although they are all good to have!).
+Instead, it is about understanding how each section focuses on a particular combination of user needs and situations.
 
 In short, the message of Diátaxis is that you are not meant to write The One Documentation that covers everything — 
 inevitably, this produces documentation which is shallow due to its breadth. Instead, focus on the strategic aspects of your documentation,