project.xpub.nl/how-to-make-your-server-run.../writings/materials.md

# Excerpts from thesis


## Entry point and backdoor

The nature of code documentation is to create entry points for people to participate in programming practices. To encode and filter knowledge, and ultimately to share it with others. This "nature", however, does not come without issues. It makes a lot of assumptions about who's reading, expecting experts, or engineers, or dudes. Its language is unwelcoming: too dense, too technical, very gendered and unable to address anyone but the neurotypical-white-cis-male programmer. Documentation requires an enormous amount of care, energy and time to be maintained, and it's done always out of budget, always as a side project, always at the end, and only if there's time left. Often code documentation acts as a barrier, gatekeeping access to the making of software.

Even if it does a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface whose reach extends through time and space. Time because it meets programmers at different moments in their lives: from the hello world till the how to uninstall, and it influences thinking about software continuously, and from different perspectives. Space because it comes in many different possible formats, and can shapeshift to serve different occasions: from simple .txt files to entire websites, from coding workshops to comments in the source code to series of video tutorial.

The question then becomes: can we make use of these backdoors to infiltrate programming practices and open more entry points from within? Code documentation is an interface between the code, the user, the developer, and the world. Living close to the source code, but at the same time being less rigid and more expressive, it seems to be an ideal surface to influence software development practices.

from [Hello Worlding - Intro](https://git.xpub.nl/kamo/thesis/src/branch/main/chapters/00_intro.md)


## Natural reader

Documentation that assumes a certain type of reader can result inaccessible. The recipient is often thought to be similar to the writer: familiar with the subject, comfortable with technicalities, and able to cut through the precise jargon and esoteric references offered as explanation. Ultimately (and in most cases) the reader is someone else. This mismatch turns entry points into barriers that filter out who can participate in coding.

Whenever too much technical proficiency is required to even read the documentation, knowledge becomes inaccesible, and confined in the ivory tower. Not filtering information becomes a filter to who can engage with it, a backfiring practice that reinforces the segmentation between who is allowed in and who is not: only the already knowledgeable ones can access, while others are kept out. Contents need to be curated, that does not mean oversimplified or generalised, but rather made legible.

Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up the digital stack.

from ["natural reader"](https://git.xpub.nl/kamo/thesis/src/branch/main/chapters/01_entry_points.md#natural-reader)

## Back till the wheel

A deep understanding of technical systems is of course admirable and desirable, given the insights it can provide into the infrastructures that shape our everyday lives. But it cannot be the only mode of access available. Deep understanding comes with its own learning curve, and it can be a barrier for many people. Yet, many, many guides resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, tracing back till the invention of the wheel.


## Cabbage

Sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about all of these at once. Programming is about balancing these different aspects depending on the situation. Keeping this balance in mind when writing code documentation gives to the writer room to adjust the tone, intensity and approach depending on who will be reading these docs.

![Wolf goat and cabbage](https://hub.xpub.nl/soupboat/~kamo/thesis/img/wolf_goat_cabbage.jpg)

## Attention to language

Whether in a large project or a small gesture, attention to language can be transformative. In code documentation it can help deconstruct the false dichotomy between programmer and user, or pro and newbie. It can create spaces that feel safer, where people are invited to participate, express themselves and contribute to the community. It can help undo the impostor syndrome that affects many programmers, and that feeds on some hidden and inaccessible fundational knowledge that is nowhere to be found in code documentation. It can help shed some light on the massive amount of work that goes into the making of software: recognising all contributions, not just those of engineers.

from [Welcoming writing](https://git.xpub.nl/kamo/thesis/src/branch/main/chapters/01_entry_points.md#welcoming-writing)
materials 1 year ago			`# Excerpts from thesis`


			`## Entry point and backdoor`

			The nature of code documentation is to create entry points for people to participate in programming practices. To encode and filter knowledge, and ultimately to share it with others. This "nature", however, does not come without issues. It makes a lot of assumptions about who's reading, expecting experts, or engineers, or dudes. Its language is unwelcoming: too dense, too technical, very gendered and unable to address anyone but the neurotypical-white-cis-male programmer. Documentation requires an enormous amount of care, energy and time to be maintained, and it's done always out of budget, always as a side project, always at the end, and only if there's time left. Often code documentation acts as a barrier, gatekeeping access to the making of software.

			Even if it does a questionable job at creating entry points, code documentation still has a lot of potential as a backdoor. It's a publishing surface whose reach extends through time and space. Time because it meets programmers at different moments in their lives: from the hello world till the how to uninstall, and it influences thinking about software continuously, and from different perspectives. Space because it comes in many different possible formats, and can shapeshift to serve different occasions: from simple .txt files to entire websites, from coding workshops to comments in the source code to series of video tutorial.

			`The question then becomes: can we make use of these backdoors to infiltrate programming practices and open more entry points from within? Code documentation is an interface between the code, the user, the developer, and the world. Living close to the source code, but at the same time being less rigid and more expressive, it seems to be an ideal surface to influence software development practices.`

			`from [Hello Worlding - Intro](https://git.xpub.nl/kamo/thesis/src/branch/main/chapters/00_intro.md)`


			`## Natural reader`

			`Documentation that assumes a certain type of reader can result inaccessible. The recipient is often thought to be similar to the writer: familiar with the subject, comfortable with technicalities, and able to cut through the precise jargon and esoteric references offered as explanation. Ultimately (and in most cases) the reader is someone else. This mismatch turns entry points into barriers that filter out who can participate in coding.`

			`Whenever too much technical proficiency is required to even read the documentation, knowledge becomes inaccesible, and confined in the ivory tower. Not filtering information becomes a filter to who can engage with it, a backfiring practice that reinforces the segmentation between who is allowed in and who is not: only the already knowledgeable ones can access, while others are kept out. Contents need to be curated, that does not mean oversimplified or generalised, but rather made legible.`

			Cultivating legibility is not an easy task, especially when it comes to computer technology: a cards castle of abstractions built on top of other abstractions. These abstractions are more than just metaphors: they are interconnected narratives and intertwined plots and main characters at the same time. The purpose of an abstraction is to function as a symbol, as a mentally manoeuvrable concept, free from the details of its technical implementation. Yet the piling up of these structures makes for a dense forest with no clear path to follow in sight. Programming is the perfect rabbit hole because of the depth and complexity of each layer that makes up the digital stack.

			`from ["natural reader"](https://git.xpub.nl/kamo/thesis/src/branch/main/chapters/01_entry_points.md#natural-reader)`

			`## Back till the wheel`

			A deep understanding of technical systems is of course admirable and desirable, given the insights it can provide into the infrastructures that shape our everyday lives. But it cannot be the only mode of access available. Deep understanding comes with its own learning curve, and it can be a barrier for many people. Yet, many, many guides resemble this setup: pieces impossible to read if before one hasn't read an equivalent illegible piece of documentation and so on, tracing back till the invention of the wheel.


			`## Cabbage`

			`Sometimes code is about performance, sometimes is about flexibility, sometimes is about accessibility, but rarely about all of these at once. Programming is about balancing these different aspects depending on the situation. Keeping this balance in mind when writing code documentation gives to the writer room to adjust the tone, intensity and approach depending on who will be reading these docs.`

			`![Wolf goat and cabbage](https://hub.xpub.nl/soupboat/~kamo/thesis/img/wolf_goat_cabbage.jpg)`

			`## Attention to language`

			Whether in a large project or a small gesture, attention to language can be transformative. In code documentation it can help deconstruct the false dichotomy between programmer and user, or pro and newbie. It can create spaces that feel safer, where people are invited to participate, express themselves and contribute to the community. It can help undo the impostor syndrome that affects many programmers, and that feeds on some hidden and inaccessible fundational knowledge that is nowhere to be found in code documentation. It can help shed some light on the massive amount of work that goes into the making of software: recognising all contributions, not just those of engineers.

			`from [Welcoming writing](https://git.xpub.nl/kamo/thesis/src/branch/main/chapters/01_entry_points.md#welcoming-writing)`