5.3 KiB
From the perspective of hosting others into our code, documentation becomes a form of hospitality. A form of care for a shared space.
In XPUB, each group begins its two-years programme by setting up a self-hosted server. We called ours Soupboat, and it houses many of our prototypes and experiments. This small server, running on a Raspberri Pi, feels like a place to call home on the internet. Over the past two years we have done all sorts of projects there: generated web-to-print publications, custom CMSs to keep track of birthdays, Etherpad documents, and soup recipes, workshops, personal wikis, and so on.
While living on a server with others, my approach to code began slowly to change. Publishing open git repositories, instead of hiding behind private ones. Writing more readme files to be more generous with friends and colleagues and tutors. Cultivating small gestures and rituals, like leaving comments in config files to remind others where to mount the next app or where to find some credentials.
This awareness grew by acknowledging the particular context of this situated software: a personal yet public server, shared between less than twenty users.
[ expand ]
shared server
shared space
tools
In many readmes for example, the explanations are tailored specifically for the Soupboat, and they cannot probably be ported 1:1 somewhere else. Code can never be ported 1:1 somewhere else. Nonetheless, the hardware and software space are prepared to host new guests.
NGINX is a web server gateway interface: a piece of software used to orchestrate the interactions between the internal network of a server and the external world. It is a central aspect of self-hosting practices and server maintainance, and because of that is also major cause of lot of headhaches. My experience with NGINX has always been one of trial and error. Being unfamiliar with the basic concepts of server itself, navigating the official documentation always proven to be really difficult. On top of that the particular situation of our configuration added some spices to the whole process, making it even more complicate. (Our server is connected to the real world through an ultra-protected institutional network, routed through a common hub with a VPN) To found a working configuration required hours and hours of attempts, and that's why the instinctive reaction was to put the same amount of hours into writing some pieces of documentation for it.
Drw is an app to gather drawings for live visuals. During a concert or a performance, the public can draw from their smartphone in realtime. On the other end of the drw server a destination receives the drawings encoded as SVG graphics, and can use them as source material for generating graphicsj. It was developed in a moment of shift from the usage of SaaS platforms such as Heroku and Northflank to a more DIY and hands-on server practice. These services make configuration and setup matters of one click, hiding and automating most of the requirements. They are super handy because even without experience one can put online an app in minutes. At the same time they feel a bit like black boxes, where because of complexity what's happening behind the scene is rendered opaque. Another aspect concerns consumption and proportions: do I really need these massive systems with millions of features, automations and magic just to put online my small drawing app that will have at max some dozens of users on a friday night performance? Drw was a moment to explore the practical implications of an alternative, self-hosted approach.
How to make your server run 4 times faster
Situated documentation
Universal solution multiplicity
-
situated docs
-
it's a 2 words title
-
docs stands for documentation
-
the documentation of coding related practices
-
code documentation
-
instruction on how to use and make software
-
how to be a developer™
-
or how to do things with code without being a developer™
-
that is actually the case for most of the people that enjoy coding
-
or a way to enjoy coding more
-
situated refers to the context of research
-
which kind of software to look into
-
situated software
-
site specific software
-
emerging from a community
-
that can rely on a a social infrastructure
-
used by specific social groups instead of generic set of users
-
that don't need to scale
-
that don't need to solve every problems
-
our software
Some intresting frictions arise when thinking about situated code documentation: how to share knowledge about very specific programming practices with other contexts? How to remain legible and accessible, for ourselves, for the ourselves of the future, and for others, while at the same time preserving specific and characteristic decisions?
Usually documentation doesn't take into account the messiness of coding contingencies, where multiple software coexist on the same server and configurations conflict or are installed with different setups. Collective learning moments and small, shared rituals can bridge the gap between the default setup described in documentation and a real-world, situated one.