There are more than 60 repositories in my git, most of them without a clear entry point for others. One idea could be to write a daily README file in order to make the projects more accessible. Make a README is a good starting point, even if it's super grounded in the corporate, githubified readme culture. Experiment with writing style and approach. Try to understand what is relevant besides technicalities. Could it offer not just a practical bootstrap but also a critical or personal perspective on the tool? Could it enforce some principles or form some habit?
When asked, hackers invariably relate the README convention to the famous scene in Lewis Carroll's Alice's Adventures In Wonderland in which Alice confronts magic munchies labeled “Eat Me” and “Drink Me”. (The Jargon File)
Code is always addressed to someone. ... We do not write code for our computers, but rather we write it for humans to read and use. Jesse Li (2020)
Coding is not just production of software, but also production of knowledge. A dialogue between human and more-than-human actors. The guestlist of this conference of the bits is often compiled by chance: the choice of a particular programming language, the coding style, the development environment and ecosystem, the infrastructure that runs the code, and so on, are the result of specific contingencies.
These contingencies are situated in precise contexts, and these contexts are different one from another. Programming is not just sharing code, but sharing context. Programming means to provide a point of view and a perspective to look at the world, before attempting to get some grip onto it with a script. That's the reason why even if source code, even when obfuscated, speaks for itself, it cannot always cast light around its surroundings.
If software illuminates an unknown, it does so through an unknowable (software) (Wendy Hui Kyong Chun, 2022)
To make place for code turns to be a necessary act of care in the process of sharing knowledge. This does not mean to constrain the usage of some piece of software, or provide opinionated solutions or tutorials, but rather letting others know where does this code come from, and where it would like to go.
Readme Driven Development
Tom Preston-Werner argues for a development practice that put the README first.
Here an excerpt
By writing your Readme first you give yourself some pretty significant advantages:
Most importantly, you’re giving yourself a chance to think through the project without the overhead of having to change code every time you change your mind about how something should be organized or what should be included in the Public API. Remember that feeling when you first started writing automated code tests and realized that you caught all kinds of errors that would have otherwise snuck into your codebase? That’s the exact same feeling you’ll have if you write the Readme for your project before you write the actual code.
As a byproduct of writing a Readme in order to know what you need to implement, you’ll have a very nice piece of documentation sitting in front of you. You’ll also find that it’s much easier to write this document at the beginning of the project when your excitement and motivation are at their highest. Retroactively writing a Readme is an absolute drag, and you’re sure to miss all kinds of important details when you do so.
If you’re working with a team of developers you get even more mileage out of your Readme. If everyone else on the team has access to this information before you’ve completed the project, then they can confidently start work on other projects that will interface with your code. Without any sort of defined interface, you have to code in serial or face reimplementing large portions of code.
It’s a lot simpler to have a discussion based on something written down. It’s easy to talk endlessly and in circles about a problem if nothing is ever put to text. The simple act of writing down a proposed solution means everyone has a concrete idea that can be argued about and iterated upon.