A
Ant Smith
Guest
TL;DR
Story-Coding reframes programming as a cognitive actβone that transcends pure rationality. It introduces a dramaturgical grammar that weaves metaphor and meaning around code, transforming technical artifacts into lived experience. This isnβt code plus documentationβitβs cognitive ignition.
When I was a junior developer back in the 80's, one guy told me βIf it was hard to write, it should be hard to read". I don't think he was entirely joking, and he perhaps contributed to the idea that C was a write-only language.
I never saw programming like that. For me it was a kind of modern magic, the way simple numbers (perhaps the simplest numbers, 0 and 1) could be impelled to flow from the imagination into the real-world; to draw dots on a page, colours on a screen, or drive motors on a mighty mechanical behemoth (I was working in the field of process control - so yes, there were lots of primitive robots around). Programming was fun, captivating even. And I believed it ought to be an understandable, shareable experience; like, I just couldn't keep this awesome 'thing' all to myself.
The key concept here is that code should be 'an understandable experience'.
This is what 'written for humans' really means. It has little to do with readability or documentation; and everything to do with experience.
For millennia, humans have used 'narrative cognition' (story-telling) to experience the abstract. So it seems a no-brainer to me that there is a place for narrative in writing (and consequently documenting) code.
To date, we have largely approached programming as a purely rational pursuit; Afterall computers themselves are purely rational constructs, right? Well, that's as maybe, but we write code for humans not machines - else why employ high-order languages at all? Bending our own thought processes to the limits of the metal, simply limits our own thoughts. The compilers and interpreters should provide the duty of abstracting rational constructs from our intent. We should express that intent in ways that are natural to human thought processes.
We can know a thing by observation, but we can only understand it by experience. A senior developer can certainly understand code just by looking at it, but that's by dint of years (or decades) of experience. Understanding is always a product of knowing and experiencing.
So, what if we can make the code not just a rational construct that can be known, but rather an experience in and of itself? I.e. make code that ignites cognition, through the power of narrative.
At this point, you are perhaps reminded of Knuth (et al.)'s Literate Programming concept, which never really flew in the mainstream. There are various criticisms of that approach, but for me the key problem lay in the fact that the results were, well, just boring. You cannot read an LP artifact and feel cognitively excited by it!
If we want code to be understood, then it needs to impel an emotional response.
I'm not interested in critiquing or dismissing Knuth (for his time, it was truly great work) - but rather to evolve.
And I think the key evolutions are:
Story-coding is about weaving rich metaphor around and within the code; applying narrative constructs that have been developed and refined since the very dawn of civilisation.
An example may make sense... which I have in this GitHub repository - check-out the expo.md to see the manual that has been extracted from the code.
Fundamentally, Story-Code is about adding an extra dimension to the code we write. It doesn't aim to replace technical documentation, nor enforce a structure upon the rational code-architecture. The code (continues to) contain the rational thought, with the story components adding the cognitive ignition - the creation of an emotional response that enables cognition, experience, feeling.
And it isn't just about documentation. That cognitive excitation is for the benefit of the coder, as much as it is for others. Writing stories is fun. Weaving stories helps to promote coherent thought.
Although much of story-coding comes down to (guided) addition of exposition to the code it's altogether a more refined approach than that. We use (well known) parts-of-story concepts (the story grammar) to devise rich metaphor for the code. We express that metaphor in the exposition, but also in the code itself - especially through the naming of objects (and consequently, the aliasing of objects that cross metaphorical boundaries).
There's no attempt to enforce a singular metaphor across an entire code base, as that would cause much dissonance between collaborators. Nor is it necessary. Good stories weave a variety of characterisations together, that create internal resonance or friction.
Finally, if we provide sufficient exposition (as distinct parts of story) then we can be confident that they will assemble into a complete narrative arc, at the appropriate time. I.e. it is common in narrative constructs to recognise a distinction between parts-of-story and plot. In Story-Coding there is a deliberate separation of these concerns. The (rational) code structure is allowed its own architecture, with the (expressive) narrative extracting and grouping components into its own plot structure.
Story-coding doesn't just call for added prose that in itself creates the cognitive spark, it offers a series of 'writing prompts' which, when coupled with the metaphor at hand, leads us towards a coherent experience.
There are various (documented) formulas for storytelling, and we are at liberty to devise our own. In fact, the grammar of story can be a foundational moment in the high-order analysis of a problem domain. There need not be a single, strict and definitive, statement of what constitutes the grammar of story (although for a given code-base, it ought to be tied down).
My own approach is grounded by my MA in Playwrighting, so is perhaps a fair starting point - albeit as yet somewhat nascent. The components (currently are):
We use the grammar to introduce comments or comment blocks within the code base that become attached to the following meaningful lexical item - e.g. a class or method or variable. Such expositions precede the thing they describe, discussing more 'why' it exists than 'how' it works. This is fundamentally orthogonal to technical notes (of how) that typically sit within (not before) the thing they discuss (e.g. Python docstrings sit inside their encapsulator).
There's a couple of exceptions to that placement expectation:
PROSE expositions help to keep the specific mechanics of code statements bound to the story, and seem most useful within BEHAVIOURS
My initial view of the story grammar was more complex, including concerns such as STORY LIMITS, PERSPECTIVES, IMPULSES and IMPROVISATIONS. Dramaturgy often thinks of CHARACTERISATIONS as having UNIQUE ABILITIES and CRITICAL FLAWS; it may also consider IMPEDIMENTS and GOALS. There's a rich seam of dramaturgical concepts that can be applied when describing code as story - whatever best ignites cognition. But the foregoing proved enough, at least initially.
The example code (Python scripts that extract expositions from Python scripts) was written using the story grammar.
The lexicographer metaphor spans 2 modules, the base class of LEXICOGRAPHICS skills and the derived class of LEXICOGRAPHER behaviours - not an unusual architectural decomposition.
The extracted story is somewhat different. The throughline that contextualises the (shared) metaphor is extracted from LEXICOGRAPHER, there is one throughline for one metaphor even though the metaphor extends across two modules. The rest of the chapter on lexicographics then intermixes expositions from the two modules to provide a coherent story that is less fractured than simply following the code structure.
The resulting story file is generated by editorialising the list of lexical entities that have expositions attached. The list is grouped and re-ordered to form the narrative arc, with subject headings inserted. The story-telling is in the code, but the story itself is plotted as a separate activity.
The most important thing in Story-Coding is to understand that it is not about documenting code. It's about adopting a cognitive, rather than rational, mindset; cognition being a superset of rationality. A story grammar helps to create a coherency when writing story-fragments, and a metaphorical throughline helps to ignite cognition in the coder and for those that come after.
Plus, metaphor is fun - and fun tasks are simply, done better.
Continue reading...
Story-Coding reframes programming as a cognitive actβone that transcends pure rationality. It introduces a dramaturgical grammar that weaves metaphor and meaning around code, transforming technical artifacts into lived experience. This isnβt code plus documentationβitβs cognitive ignition.
When I was a junior developer back in the 80's, one guy told me βIf it was hard to write, it should be hard to read". I don't think he was entirely joking, and he perhaps contributed to the idea that C was a write-only language.
I never saw programming like that. For me it was a kind of modern magic, the way simple numbers (perhaps the simplest numbers, 0 and 1) could be impelled to flow from the imagination into the real-world; to draw dots on a page, colours on a screen, or drive motors on a mighty mechanical behemoth (I was working in the field of process control - so yes, there were lots of primitive robots around). Programming was fun, captivating even. And I believed it ought to be an understandable, shareable experience; like, I just couldn't keep this awesome 'thing' all to myself.
The key concept here is that code should be 'an understandable experience'.
This is what 'written for humans' really means. It has little to do with readability or documentation; and everything to do with experience.
For millennia, humans have used 'narrative cognition' (story-telling) to experience the abstract. So it seems a no-brainer to me that there is a place for narrative in writing (and consequently documenting) code.
On Understanding
To date, we have largely approached programming as a purely rational pursuit; Afterall computers themselves are purely rational constructs, right? Well, that's as maybe, but we write code for humans not machines - else why employ high-order languages at all? Bending our own thought processes to the limits of the metal, simply limits our own thoughts. The compilers and interpreters should provide the duty of abstracting rational constructs from our intent. We should express that intent in ways that are natural to human thought processes.
We can know a thing by observation, but we can only understand it by experience. A senior developer can certainly understand code just by looking at it, but that's by dint of years (or decades) of experience. Understanding is always a product of knowing and experiencing.
So, what if we can make the code not just a rational construct that can be known, but rather an experience in and of itself? I.e. make code that ignites cognition, through the power of narrative.
On Excitation
At this point, you are perhaps reminded of Knuth (et al.)'s Literate Programming concept, which never really flew in the mainstream. There are various criticisms of that approach, but for me the key problem lay in the fact that the results were, well, just boring. You cannot read an LP artifact and feel cognitively excited by it!
If we want code to be understood, then it needs to impel an emotional response.
I'm not interested in critiquing or dismissing Knuth (for his time, it was truly great work) - but rather to evolve.
And I think the key evolutions are:
- To not just annotate the code in-place, but to apply a grammar of story
- To not enforce a rigid structure, but to provide for the creation of a narrative arc that can be orthogonal to the code structure
- To not require a singular authorial voice, but to allow for a chorus of characterisations
Story-coding is about weaving rich metaphor around and within the code; applying narrative constructs that have been developed and refined since the very dawn of civilisation.
An example may make sense... which I have in this GitHub repository - check-out the expo.md to see the manual that has been extracted from the code.
Basics of story-code
Fundamentally, Story-Code is about adding an extra dimension to the code we write. It doesn't aim to replace technical documentation, nor enforce a structure upon the rational code-architecture. The code (continues to) contain the rational thought, with the story components adding the cognitive ignition - the creation of an emotional response that enables cognition, experience, feeling.
And it isn't just about documentation. That cognitive excitation is for the benefit of the coder, as much as it is for others. Writing stories is fun. Weaving stories helps to promote coherent thought.
Although much of story-coding comes down to (guided) addition of exposition to the code it's altogether a more refined approach than that. We use (well known) parts-of-story concepts (the story grammar) to devise rich metaphor for the code. We express that metaphor in the exposition, but also in the code itself - especially through the naming of objects (and consequently, the aliasing of objects that cross metaphorical boundaries).
There's no attempt to enforce a singular metaphor across an entire code base, as that would cause much dissonance between collaborators. Nor is it necessary. Good stories weave a variety of characterisations together, that create internal resonance or friction.
Finally, if we provide sufficient exposition (as distinct parts of story) then we can be confident that they will assemble into a complete narrative arc, at the appropriate time. I.e. it is common in narrative constructs to recognise a distinction between parts-of-story and plot. In Story-Coding there is a deliberate separation of these concerns. The (rational) code structure is allowed its own architecture, with the (expressive) narrative extracting and grouping components into its own plot structure.
Story Grammar
Story-coding doesn't just call for added prose that in itself creates the cognitive spark, it offers a series of 'writing prompts' which, when coupled with the metaphor at hand, leads us towards a coherent experience.
There are various (documented) formulas for storytelling, and we are at liberty to devise our own. In fact, the grammar of story can be a foundational moment in the high-order analysis of a problem domain. There need not be a single, strict and definitive, statement of what constitutes the grammar of story (although for a given code-base, it ought to be tied down).
My own approach is grounded by my MA in Playwrighting, so is perhaps a fair starting point - albeit as yet somewhat nascent. The components (currently are):
- WORLD VIEW: An initial scene setting discourse at the application level. Also introduces the various metaphors that will be employed
- CONTINUUM: Description of an 'alien entity' - something that intrudes into the story world, possibly in its own metaphor (typically imported or included concepts)
- THROUGHLINE: A discourse that connects the current metaphor (of the module in hand) with the world view. Helps us to relate metaphorical concepts to code mechanics, typically therefore, one per module.
- CHARACTERISATION: A figuration or affordance, a complex package of smaller story parts with broad purpose. Key players in the story.
- KNOWLEDGE: Things that are known, or come to be known.
- DISPOSITION: states or attitudes
- BEHAVIOUR: A sequence or iteration of actions based on knowledge and dispositions
- MECHANISM: Transformative actions with material effects
- SKILLS: Informative actions
- FLAWS: All the stuff that goes wrong
- PROSE: More detailed discussions...
We use the grammar to introduce comments or comment blocks within the code base that become attached to the following meaningful lexical item - e.g. a class or method or variable. Such expositions precede the thing they describe, discussing more 'why' it exists than 'how' it works. This is fundamentally orthogonal to technical notes (of how) that typically sit within (not before) the thing they discuss (e.g. Python docstrings sit inside their encapsulator).
There's a couple of exceptions to that placement expectation:
- Module-level expositions (WORLD VIEW and THROUGHLINE) sit within the module they relate to
- PROSE expositions weave around the code they relate to
PROSE expositions help to keep the specific mechanics of code statements bound to the story, and seem most useful within BEHAVIOURS
My initial view of the story grammar was more complex, including concerns such as STORY LIMITS, PERSPECTIVES, IMPULSES and IMPROVISATIONS. Dramaturgy often thinks of CHARACTERISATIONS as having UNIQUE ABILITIES and CRITICAL FLAWS; it may also consider IMPEDIMENTS and GOALS. There's a rich seam of dramaturgical concepts that can be applied when describing code as story - whatever best ignites cognition. But the foregoing proved enough, at least initially.
Narrative Arc
The example code (Python scripts that extract expositions from Python scripts) was written using the story grammar.
The lexicographer metaphor spans 2 modules, the base class of LEXICOGRAPHICS skills and the derived class of LEXICOGRAPHER behaviours - not an unusual architectural decomposition.
The extracted story is somewhat different. The throughline that contextualises the (shared) metaphor is extracted from LEXICOGRAPHER, there is one throughline for one metaphor even though the metaphor extends across two modules. The rest of the chapter on lexicographics then intermixes expositions from the two modules to provide a coherent story that is less fractured than simply following the code structure.
The resulting story file is generated by editorialising the list of lexical entities that have expositions attached. The list is grouped and re-ordered to form the narrative arc, with subject headings inserted. The story-telling is in the code, but the story itself is plotted as a separate activity.
Epilogue
The most important thing in Story-Coding is to understand that it is not about documenting code. It's about adopting a cognitive, rather than rational, mindset; cognition being a superset of rationality. A story grammar helps to create a coherency when writing story-fragments, and a metaphorical throughline helps to ignite cognition in the coder and for those that come after.
Plus, metaphor is fun - and fun tasks are simply, done better.
Continue reading...
