From c266fb190d9368108b1b232302129c1c7cf1ac7a Mon Sep 17 00:00:00 2001 From: "kam (from the studio)" Date: Tue, 7 Feb 2023 19:17:44 +0100 Subject: [PATCH] formats and framework --- chapters/01_who_is_reading.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/chapters/01_who_is_reading.md b/chapters/01_who_is_reading.md index 23ae8db..c07ae86 100644 --- a/chapters/01_who_is_reading.md +++ b/chapters/01_who_is_reading.md @@ -43,10 +43,14 @@ The devil is in the details, and software as well: the translation between human Documentation is not just for beginners: it's a code companion. One never stops reading. Even experienced programmers must refer to docs when first encountering a software, and return to the references when they need a refresher on the syntax of a particular command. They continuously look at code from multiple distances: close to the source code through lines of comment—ignored by the machine, but much appreciated by fellows developers—or from printed books, along with pages of explanations and use cases. -This tentacular surface can reach a programmer in different moment of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring colored images. +This tentacular surface can reach a programmer in different moment of their life: from the _hello world_ to the _how to uninstall_. This is possible thanks to the multitude of shapes documentation can take: video tutorials and commands cheatsheets, _README_ files and complete guides featuring colored images. Each format comes with different approaches and intentions, and in response to different needs. + +Daniele Procida proposes a systematic approach to organize this wealth of formats (diataxis.fr, 2017). + +Using four main modes - different documentations for different readers -- wrap up +- wrap up aka: doc world building not only for newcomers but everyone ``` note: below are materials from previous writings @@ -76,11 +80,11 @@ Cuneiform writing and comments. (even though this is cuneiform writing and synta ## Different distances -Who is writing could be the very same developer or someone else. Writings come with different approaches and intentions, and as response to different needs. +Who is writing could be the very same developer or someone else. Writings ## Different documentation for different readers -Documentation comes in many different forms. Daniele Procida offers a systematic approach to organize this wealth of formats (diataxis.fr, 2017). +Documentation comes in many different forms. His framework is built at the intersection of two axis: one goes from theoretical to practical knowledges, while the other from study to work. Here _study_ could be read as _learning_ or _understanding_, while _working_ means getting things done. Another powerful couple of synonims is _receiving_ and _giving_: by combining the renamed axis we can get a glimpse of the flow of knoweldge involved in documentation.