care for code page

contents/care_for_code.md

@@ -0,0 +1,101 @@
+---
+title: Care for code - Documentation session
+---
+
+# Care for code - Documentation session
+
+Two hours of headspace to write some _code documentation_. For your new coding project, for the cryptic library you downloaded recently, for a script that you want to share with others!
+
+Too many pieces of code are left alone out there: without an entry point, forgotten, while outside is raining. Wouldn't it be nice to take care of them?
+
+Enter the documentation sessions. Two hours where to sit with source code and write something about it. From simple instructions to in-depth explanations, or maybe some drawings to illustrate the overall process. You name it.
+
+Writing documentation is tricky! But let's face this together: prompts and suggestions will be offered for inspiration, and coffee and snacks for restoration. If you want there will be space to share your work and exchange feedback, if not no prob: just enjoy the cozy music and write some docs.
+
+---
+
+These sessions grow out of the contradiction of being frustrated in having to deal with undocumented pieces of software, and at the same time never documenting anything. While for sure there is some thrill in understanding how to stitch codes together, the lack of documentation poses a great hindrance for the participation of diverse knowledges in the making of software.
+
+At the same time, this very lack of documentation could be used as a starting point.
+
+Documentation is a space that interfaces between the code, the user, the developer, and the world. A space with potential to renegotiate and reclaim given margins and entry points. A chance to overwrite what is normalized, and let more voices participate in the discourse that is software.
+
+Documentation is a way to produce narrations around software. To create a world for the code to inhabit, to stretch what is possible to do or to think with it. Documentation is a space for the political in the software. A surface that could host ideas in close contact with code, letting them entangle and shape each other.
+
+## Ok ok ok ok but where to start?
+
+One can start documenting code in many different ways. Every piece of software and every situation require something slightly different, so it's not that there's a right or wrong way to do it.
+
+Here some prompts!!
+<!-- Feel free to add more `??? note that this could be an open repo` -->
+
+### Start from the readers!
+
+For who are you writing this documentation for?
+
+Keep in mind that there are many kinds of reader! Beginners and experienced programmers alike. Friends and strangers. Future selves. Everyone reading the same documentation, but from a diverse perspective!
+
+This does not mean that what you are writing has to meet the needs of everyone everywhere all at once. Rather, it's a way to acknowledge that different readers come with different expectations.
+
+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 some code, 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.
+
+A useful resource to navigate programmers' needs with documentation is a framework proposed by Daniele Procida. By leveraging between practical steps and theoretical knowledge, it charts four main modes of technical writing. Each format comes with its own approach and intentions, and in response to different questions.
+
+Tutorials offer entry points for the newcomers, while explanations unveal core mechanisms for more navigated readers. How-to guides teach how to get the work done, while references report lists of information ready to be consulted. Different documentations for different readers for the same code.
+
+Find more at [diataxis.fr](https://diataxis.fr).
+
+![diataxis scheme](https://hub.xpub.nl/soupboat/~kamo/thesis/img/diataxis.jpg)
+
+### Start from the code!
+
+Another way to start is by commenting directly the source code.
+
+There are many constraints here: no formatting, limited space, no way to insert images, an exagerate level of technical details, etc. For sure (for sure?) not the place to write an entire manual. These limitations however offer a good chance to focus and explain what the code is doing in the clearest way possible.
+
+Code and comments have their own pace, flow and logic. One does not read code as they would read a traditional text (debatalbe)! It's rare for a script to run in a linear fashion, from top to bottom: more often it jumps here and there, calling functions and methods scattered around the codebase.
+
+Guide your reader!
+
+There are many possible strategies: order the comments progressively, rearrange the functions to follow a more sequential development, organize the code into blocks, link to external references, etc.
+
+<!-- knuth intro of literate programming -->
+
+### Start from an image!
+
+Reading source code feels like being an ant walking on a big painting. You can see the strokes of a brush and have an intuition of their direction, but what's missing is an overall idea of how the composition flows. Documentation provides guidance through the bunch of functions and statements that makes software, a bird's eye perspective.
+
+Sometimes an image is worth a thousand words. To illustrate the different steps of the process, or to give an overview of the program's lifecycle.
+
+Flowcharts and Nassi-Schneiderman charts are traditional options in technical writing, but things don't have to be sooo strict and rigorous. Let your visual intelligence and the ones of your readers hangout together. Offer other ways to think about code: sometimes it's easier with a concrete metaphor!
+
+![chae api]()
+Explanation of an API by Chaeyoung Kim
+
+![frogs]()
+Lifecycle of an etherpad document when stored in the Padliography.
+
+![nassi schneiderman]()
+
+### Start with someone else!
+
+Teaming up with others comes with several benefits!
+
+Teaming up reduces the workload on the individual: writing docs is demanding and delicate. It requires focus and care and energies: it's like gardening, or orthopedics, or cooking, or policymaking.
+
+Teaming up offers multiple pairs of eyes to keep track of code. Here, even before releasing the docs, it's necessary to find a middle ground between different perspectives. Beginner and experienced programmers can write docs together! The process is beneficial for both, and the resulting docs comes with more facets.
+
+Teaming up comes handy to undo assumptions and to open more entry points. A shared effort is already a moment of publishing. Making meaning together. A way to join different knowledges and skills, to broaden participation in the making of software.
+
+## Pairing docs and code
+
+Where to publish the documentation is up to you, and depends on the context your coding with. It could be close to the source code, such as a txt file in the same directory, or a ReadMe in the git repository. It could be more detached and physical: a printed booklet, a poster on a wall, a cheatsheet of references.
+
+The one and only important thing to keep in mind is: pair docs and code.
+Documentation is unfortunately just a snapshot of how a system work. A snapshot situated in a particular moment of time, referring to specific versions, implementations and languages. Be sure to offer this context to the reader! State to which version of the code this documentation refers!
+
+Even worse than not having documentation, is to have docs that feel wrong, and don't match with the code they are documenting.
+
+Here the making of software resembles gardening: code changes continuously, and overflow the specifications of a manual. With care and effort, documenting means to trim and prune and transplant and bend code and explanations together.
+
+<!-- semantic versioning? -->