From c0feb9df9e7133d68afad8e4d363b4107701f99b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A9cate=20Kleidukos?= Date: Thu, 15 Aug 2024 22:54:36 +0200 Subject: [PATCH] Re-org for images --- README.md | 19 ++++- .../flow-of-documentation.png | Bin 0 -> 39152 bytes .../index.md} | 77 ++++++++++++------ 3 files changed, 66 insertions(+), 30 deletions(-) create mode 100644 content/documentation-best-practices/flow-of-documentation.png rename content/{2024-08-03-documentation-best-practices.md => documentation-best-practices/index.md} (75%) 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 0000000000000000000000000000000000000000..46b28c1516a106c2e4a01df1ca1ee60620023d56 GIT binary patch literal 39152 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 bU;JleyR7oD)0Hcm0SG)@{an^LB{Ts5e%)%$ literal 0 HcmV?d00001 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..32c3716 100644 --- a/content/2024-08-03-documentation-best-practices.md +++ b/content/documentation-best-practices/index.md @@ -1,6 +1,6 @@ +++ title = "Documentation Best Practices" -date = 2024-08-02 +date = 2024-08-19 [taxonomies] authors = ["Hécate"] categories = ["Haddock"] @@ -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 @@ -58,21 +57,42 @@ your project. > “When you refer to something, make sure the direction of the reference is from the more volatile to the more stable elements” +> > -- 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 +111,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,