@@ 0,0 1,155 @@
title: Free-flowing software stories
There's an argument that despite the prevalence of search engines,
Wikipedia, and large language models (LLMs), we still need to [know
things][know]. We shouldn't just look things up.
I think this argument could use better examples. Canonical knowledge,
like Newtonian physics and text encodings, is not the best example of
something you should memorize. Sure, you'd be faster at solving a problem
if you know something relevant to that problem. But in some contexts,
predicting what problem you'll have, and what knowledge you will need,
is hard. Knowing _how_ to look up information is nearly as effective
as knowing _that_ a million facts are true, and doesn't require me to
adopt the habit of [spaced repetition].
[spaced repetition]: https://controlaltbackspace.org/repeat/
## Spaced out
I used spaced repetition software (SRS) for five months in 2022. I was
looking for a job and not feeling so good. I hoped my job interviews
would go better if I had memorized a certain set of facts. I wrote 617
Anki cards, used the app every day, and savored the challenge of writing
good cards. I gave up before I got a job.
What actually helped my interviews was focusing on my impact. The real
problem was that I didn't feel confident. I didn't feel confident because
I was telling the story of my previous work in terms of activities
rather than impact. I hadn't made sense of what I'd done before. I
didn't understand what my work meant to hiring managers. In their jargon,
I didn't understand my differentiators.
To me, a differentiator is a circuit element, not an attribute of a job
candidate. But I've read some Gregory Bateson. I remember his motto:
> Information is a difference that makes a difference.
Daniel Dennett has recently examined the idea [too][edge].
## Dennett does differentiate
Dennett used to think you could reduce meaning to propositions, but
he changed his mind. He now argues that semantic information generally
isn't propositional. Propositions sometimes usefully approximate
meaning. But if you want to get semantic information completely,
you can't assume a proposition will do the job.
In chapter six of of his book _From Bacteria to Bach and Back_, he connects
semantic information to design, and design to research and development
> So let’s consider, as a tentative proposal, defining semantic
> information as _design worth getting_, and let’s leave the term
> “design” as noncommittal as possible for the time being, allowing only
> for the point I stressed in chapter 3, that design without a designer
> (in the sense of an intelligent designer) is a real and important
> category. Design always involves R&D work of one sort or another, and now
> we can say what kind of work it is: using available _semantic information_
> to improve the prospects of something _by adjusting its parts in some
> appropriate way_. (An organism can improve its prospects by acquiring
> energy or materials—food, medicine, a new shell—but these are not
> design improvements. Rather, they are just instances of refueling or
> rebuilding one’s existing design.) One can actually improve one’s
> design as an agent in the world by just learning useful facts (about
> where the fishing is good, who your friends are).
## I don't get it
The four-strong embedded software team at my company is having a tough
time. We maintain a lot of software we didn't write. We all joined the
company within the last three years. Our software is complex. We have
the artifacts, but the artifacts are not the same thing as the design
(in Dennett's sense) of the people who created it. It's hard to for us
to improve our design without the original authors around to mentor us.
Our software is not canonical like Newtonian physics. It's
esoteric. There's public information about it, but it hasn't benefitted
from centuries of cultural evolution. It isn't private thoughts[^1],
but also isn't widely understood.
[^1]: Sometimes I get the urge to query the web for the location of an
object in my house.
I'd thought of my job as maintaining, modernizing, or reverse engineering
old software. But that understanding has continuously underestimated the
difficulty of job. It keeps getting harder. Is it software archaeology?
Actual archaeologists use the term "software archaeology" as a
[joke]. Meanwhile, Embarcadero has made it into a [solution], at least
for Java. It definitely overlaps with reverse engineering, but focuses
more on the social context ("Why is it designed like this?") than the
technical artifact ("What is its design?").
There are cases where reverse engineering is helped by software
archaeology. When it is difficult to glean the design from the artifact,
the social context can provide critical clues.
## Regime change
Information regimens are common in organizations. Confluence documents
always have an author, a set of viewers, a set of tags, a comment
thread. We try to chase down what matters with mental models like OKRs. I
like the idea of an architecture decision record (ADR) as a way to ease
archaeology for future people. But I'm astonished at how [belabored] it is,
especially the "status" section. How can you label a decision as "accepted"?
_Who_ accepted it? Who didn't?
Acronym-laden formats have tradeoffs like propositions. A rigid data
format is consistent and predictable, but sometimes infeasible. Things
that matter don't always fit into a consistent format. Just because you
have a consistent format doesn't mean your readers are free from the
burden of interpretation.
People need to learn things, but each person learns for themselves. Learning
isn't the accumulation of information; it is the redesigning of an organism.
Knowledge can't really be _transferred_, but it can be _developed_.
We want to encourage the development of knowledge. My current
hypothesis? As far as _formats_ for semantic information go, **stories**
and **dialogues** are probably the best you can get. Smullyan's [Is God
a Taoist?][taoist], my favorite dialogue, doesn't follow "bottom line
up front" (BLUF) or the [Minto pyramid]. The conclusion is at the end,
after inquiry has dug up what matters. Maybe information optimized for
fast consumption isn't a good fit for archaeology.
[Minto pyramid]: https://untools.co/minto-pyramid
## Try it
When somebody has a story worth telling, let them share it. The medium
doesn't matter. Pick something convenient for your situation. Don't
enforce a rigid schema. Encourage semantic information.
When I worked with the Auklet team, I told stories through Jira work
logs. My boss loved it and my coworkers found useful info in my work logs.
At my current company, I've put a `stories/` directory in the main
project repository. This is inspired by the idea of keeping documentation
in the repository. Maybe a story is social documentation. In software
archaeology, social documentation makes a difference.