First published on

Note taking and explaining systems

Note taking and explaining systems

Weeknotes for week beginning 12th July 2021

Note taking

A couple of weeks ago I moved into a new role at Made Tech, looking across a wider range of products and projects at Hackney Council. This has inevitably come with an influx of new people to meet and new things to get my head around. I picked up a Remarkable 2, on the advice of my predecessor (really I've wanted one for months, they just helped tip me over the edge 😅), to help me structure my notes, maintain a better record of the discussions I'm having, and to keep myself honest about completing the things I've promised to do. So far I'm firmly in the position of taking lots of notes but I'm still not at a place where I'm able to digest them and act on them. Improving this is a goal of mine for the next few weeks.

Explaining systems

I got a direct message on Twitter last week about my Train Departure Screen Raspberry Pi project; the message was asking for help in understanding the code I'd written to power the screen. I had intended to reply with a brief overview of how the code works, the main entry points and primary processes / methods, but I felt it might be more useful if I pulled that out of a direct message and instead published a full write up for others to enjoy and learn from too.

I have started doing this and hope to publish something soon, although I was stopped in my tracks by a totally coincidental discussion that happened at work about explaining the behaviour of a system or application. The discussion largely centred around the difference between explaining the codebase (aka. the codebase is the application) versus explaining the abstract capabilities of the application (of which the codebase is just one representation of those capabilities).

The discussion highlighted a few interesting concepts and tools, notably the concept of 'Moldable Development' via Glamorous Toolkit and Projectional Editing, a way of understanding and editing a system through more contextually-relevant projections. While I suspect I will finish writing up the application in a more traditional way (focussing on the codebase itself), given the fairly simple nature of the system it has presented a good opportunity to think about alternative ways of explaining it and whether these concepts could help me publish something that would be useful for different audiences. I hope to dive into in this further the coming weeks.