diff --git a/README.md b/README.md index 1b19050..73c1543 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ Once you have cloned this repository, run `npm install` and `npm run abridge` to #### Name -Blog posts are located in the `content` directory, as markdown files. The files themselves start with the (expected) date of publication -and contain their title in a "slug" format (alphanumeric characters, words separated by a hyphen, all lowercase): +Blog posts are located in the `content` directory, as markdown files. The files themselves contain +their title in a "slug" format (alphanumeric characters, words separated by a hyphen, all lowercase): ``` -2024-08-03-documentation-best-practices.md +documentation-best-practices.md ``` #### Front-matter @@ -45,6 +45,19 @@ You can manually delimit where it ends by inserting `` on a newline Otherwise, in the absence of this comment, the first 150 characters will be used by Zola +#### Images and other files + +If you want to add images to your blog post, create a folder named after the blog post, and write the content of the post to an `index.md` +file within it. Put your associated files in the same directory. + +For instance: + +``` +documentation-best-practices +├── flow-of-documentation.png +└── index.md +``` + ### Local preview Run `zola serve --drafts` in order to serve the website and automatically render it when files change. diff --git a/content/documentation-best-practices/flow-of-documentation.png b/content/documentation-best-practices/flow-of-documentation.png new file mode 100644 index 0000000..46b28c1 Binary files /dev/null and b/content/documentation-best-practices/flow-of-documentation.png differ diff --git a/content/2024-08-03-documentation-best-practices.md b/content/documentation-best-practices/index.md similarity index 75% rename from content/2024-08-03-documentation-best-practices.md rename to content/documentation-best-practices/index.md index 33e70c3..b0d52e5 100644 --- a/content/2024-08-03-documentation-best-practices.md +++ b/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: +flow of documentation + +
Code for this diagram + +```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) -``` +
+ +> 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. - +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: + -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,