README cultures
Thursday, August 24th, 2023
If we want to have truly composable and interoperable teams (meaning, people participate in multiple DAOs and come in and out as they need as one would a freelancing engagement but more tightly integrated culturally and financially as one would in a for-hire situation), we need clear interfaces.
Heck, even if we just want to work within a company, we need this.
Self-descriptive APIs have this.[1] Shouldn't humans, who are far more chaotic and destructive when communication is misaligned, have something like this?
I refer this to a "README" document, but others have called it a Personal User Manual[2]. Exact same idea.
I am writing my own version that, independently, comes up with similar categories as the PUM template.
But first, what is it and why?
In the same way that a self-descriptive API helps developers or other APIs to navigate its resources and parameters, a README document helps to define how someone interacts, specifically around receiving communication (input), interpreting (processing), and communicates (output).
These are wildly different from person to person since people have different personalities and archetypes. However, if other people aren't able to quickly calibrate (or vice-versa) to the different protocols each of us are on, miscommunication occurs.
Alot of times, companies "just work" because a set of commonly accepted protocols are agreed upon tacitly. This can be via the self-selection process (e.g. I like to deal with people whom I like to deal with) for individuals or for the company.
But implied guidelines are harder than clear interfaces.
While humans aren't as deterministic as computers, we do often color between the lines.
The README doc is just that, the lines. But these are important depending on context.
Lines in a coloring book are helpful. Line in a narrow two-way winding highway, critical.
Now for some markdown:
| Category | Description |
|---|---|
| Default question asking myself entering conversations | Think hard and self-reflect: what is the story you tell yourself in most conversations? |
| Most joyful types of communications | Describe the most successful and fruitful conversations for both sides |
| Your area of improvement | Describe a weakness you are actively working on |
| Overall preferred medium (protocol generalized) | Describing the preferred way to interact - in-person, text, email, phone, zoom |
| Context: Complex or Early Stage | How to handle complex conversations |
| Context: Information Exchange / Updates | How is mostly one-way information best handled |
| Comfort level with async and modality | Specifically, approach and philosophy to async |
| Self-description of style (content type) | Describe in as realistic and honest approach to your own style |
| Misperceptions (error handling) | How might your approach been misunderstood in the past AND what it really means |
| Mis matched inputs (client side errors - 400) | What common ways your shadow side gets brought out by others |
| Ways inputs escalate to conflict (conflict - 409) | Common patterns that put you into the red zone |
| SLAs - inbound | What your likely turnaround time will be and how to escalate |
| SLAs - outbound | What your expected SLA is and hopefully it's aligned with your own! |
At this point you might be thinking, "WTF?!"
Is this too prescriptive?
The point of it is to lean more on your challenges and preferences and ways you can be misunderstood.
The challenge is being honest with yourself. You can lean a bit into your aspirations, but creating a false self while knowing it is your shadow self that shows up does no one any favors.
Here's how I am working on my own version.
GitHub - vpsfreecz/haveapi: Framework for creating self-describing APIs "A self-describing API knows about itself what resources and actions it contains. It is able to send this information to clients in a machine-readable form. The API responds to HTTP method
OPTIONSand returns the description of available resources, actions, their input/output parameters, labels, text notes, data types, validators and example usage." ↩︎