Rediscovering the .plan File

At the end of 2020, I published a long-form post on discovering a computer programming career by building a game modification. In that article, I mentioned a communal practice whereby noting ideas and todos originally served by the UNIX finger command. The command publicly exposes the content of a .plan file.

At the demise of fingers life in the late 1990s, the practice was epitomized by John Carmack which he had a unique approach to crafting information within. His practice was admired by the community and was later romanticized in Masters of Doom and mentioned in Game Engine Black Book DOOM.

Since my article was published, I started a side project to rebuild that modification. My primary goal is to rebuild the experience with the compatibility of the final game patch. And in doing so, I have an interesting observation to share.

What is learnings.md?

Out of nostalgia, I started a new .plan file that captures the interesting minutiae within the small project. But with the demise of finger, I'm focusing every meaningful clarification from research, behavior, or a [enter your favorite search engine] result in a file I call learnings.md (see example below).

learnings.md is a chronological list that captures interesting findings from the developer's perspective. With some months into the project, it's been an investment of learning game development context, dockerization, build pipelining, Powershell scripting, and the oddities of cross-compilation of Linux, Windows, and macOS. Surprisingly it's a firehose of valuable technical findings. And it's being captured.

While I have never seen this style out in the ether, I am confident that there are developers out there doing this in their own way, organizing their found knowledge and making it highly searchable. Wiki's come to mind.

And in working on so many different projects, I wonder why this is such a late discovery for me, a small gem that can be shared with others while the sausage is made, highlighting all the things intrinsically I should know.

Why I like learnings.md

This learnings.md file is an unproven practice, but I write since it's been a helpful feedback loop in a development environment. Here are a few reasons why I like it:

1. This learnings.md reinforces the learning through writing down the note. There is some friction to this habit; however, it's beneficial by way of remembering the learned concept spatially in time.
2. The learnings.md file is used as a primary place to look up information when attempting to remember the learning, as things in development come up more than once (that I forgot the core lesson or how-to). I've used it as a lookup to clarifying the technical context, e.g., resources on how to operate docker on Windows within VirtualBox without Hyper-V.
3. The file is lightweight. It could become a pivot to build out a small search index when its length becomes unwieldy.
4. It is a continual practice of yak-shaving search debriefs - when there are too many tabs open in [enter your favorite browser], I'll go ahead and walk each tab, determine if there was learning from that research, write it out in learnings.md, and then close the tab. Or close the tab outright, as there was no value.
5. Finally, I'll stretch to say a learnings.md file could be useful for the next engineer to review and walk the file to see what took hours of struggle to resolve (or not).

Spatial and temporal pedantic reinforcement

I was reluctant to write about this practice because, just like a .plan file, it is a very personal experience that will unlikely map to other's practices. I remember reading once that .plan files were used to wax lyrical or write poems about growing old.

However, in such an environment of expert Googling, I felt I had to keep track of the knowledge somewhere. This reminds me of an unknown quote:

The discovery of information is not really important. But this information becomes important when it is appreciated.

And when I seem in a jam vaguely remembering the technical once prior, I appreciated this file more than a handful of times. I like that it's there, a crutch, closer than [enter your favorite search engine]'s cozy doormat. So I'll experiment with the learnings.md file and see where it takes me.

Realistically? It will become a pedantic foxhole where link rot will thrive, and the poem I'll type is how screwed dependency management became.

---

learnings.md example

1. I learned that using the git patch tool for commits may require splitting hunks manually. See this thread about "Sorry cannot split this hunk."
2. To show the full diff of a stash in git, use git stash show -p. See this thread as well.
3. An interesting read on how the Source engine implements the Server-Client networking architecture. See this thread here.
4. To fake lag (and to test prediction) in Half-Life, use the command fakelag to simulate the behavior one would experience with a less than ideal ping.
5. Windows 8 does not support running native windows docker containers. Support began with Server 2016 / Windows 10.
6. An interesting document on how to compile Half-Life 2 models here. Covers full breakdown of all formats.
7. For debugging the number of current edicts in Half-Life, use the macro NUMBER_OF_ENTITIES() or the global parameter gpGlobals->maxEntities.
8. An excellent post on the breakdown of Powershell modules. Describes best practices for spliting up large scripts. Additionally a post on unapproved verbs warning.
9. To run ffmpeg on a docker container using servercore, there are two missing dlls that must be added. See this thread on the detail of those dependencies, and the dlls themselves.
10. To dockerize visual studio 2019, here is the full list of workload segments that can be installed. This thread was also helpful in the commands to dockerize Visual Studio.
11. How to add numerous folders to a zip file in succession.
12. Powershell modules are cached in each session. If changes are made to a module in that session, which happens in development frequently, use the -force parameter. See this thread.
13. Dot sourcing in Powershell requires a fully qualified path to the script to be imported. It does not accept relative paths. Also, this was helpful.
14. Wad locations can be split outside of the map file using a wad configuration. See this post from zhlt here. This parameter list was helpful as well.
15. Here is a thread on how best to unrar a file in Powershell.
16. Use caution with the use of pev->nextthink = -1. If used incorrectly, it may shortcircuit the entity's removal, e.g. when inheriting from CGrenade.
17. Powershell escape characters are backticks, not slashes. See this thread for more info.
18. When investigating how to convert the old version of milkshape model files from 2000, this changelog was valuable to pinpoint the version that had the tool to perform the conversion. Version 1.65 on the milkshape3d forums had the conversion tool available.

view raw learnings.md hosted with ❤ by GitHub

Comments

[Devtonian]

This is a great idea. I still have a whole archive of Carmack's .plan files.

I plan (no pun intended) to do something similar for my future projects. For now, I've decided to share a more or less frequent diary of my daily activities, experiences and learnings while working. Helpful to keep my mind tidy, and if somebody finds some use in it, all the better.