I’m a software developer and a technical writer so I take bunch of different types of notes about technology. I try to categorize them here but when I’m writing them, I don’t really think in terms of these: I note what I have to note and they usually become one of these in hindsight. I also don’t mark or label them or put them into separate folders based on these categorizations.
Note types
Snippets
First type is snippets, which are usually one use case of tool or technology per note. As an example, I have one note called “git branch column” that has the following:
```
git branch --column
# or permanently
git config --global column.ui auto
```
displays branches in a column mode.
It holds a single action that I can do with git with a bit of naming/paragraph to help me find it later. Second example is a note called “Postgres expanded display” where I document how and why to use the \x command with Postgres to make wide outputs more readable.
I usually find these from blog posts, conference/meetup talks or through my own work and I document them in these notes that all link back to the main topic (in this case, git and postgres respectively).
I find myself coming back to them constantly. It’s grown into kinda like my own Stack Overflow of sorts.
Tools and libraries
Whenever I see an interesting tool that I’m starting to use or am planning to give a try at some point, I create a note for it, add some relevant links (like blog posts or toots where I found it from) and write a short description of why I think at the time it might be a good tool to use.
As time goes on, if I run into other sources that discuss it, I add them as reference links to the note and extend it with my own experiences.
Running notes
I call these running notes, Sam Bleckley calls them Lab Notebooks, Charles Féval calls it a Work journal and Tanner Christensen also refers to them as work journals. All of these three are slightly different variations as are mine too.
When I start working on something (for example a bug or feature ticket at work), I create a new note for it and start working on it, logging my thoughts, assumptions, steps I take, discussions I have and so on. They are very raw and kind of append-only in a way that if I notice something was wrong, I don’t delete it. I want to keep a history of where I went wrong as that can also help finetune the processes or improve documentation once I’m done. I do sometimes polish them up a bit once I’m done (meaning adding headings, improving flow, adding links to documentation) but I don’t change the content.
In these, I also keep links to the tickets and pull requests and other artefacts.
At work, these usually live in my Obsidian and also contain some of the design work like writing the requirements, business case, potential test cases and architecture ideas in my own words to make sure I understand what I’m building and for who.
When I work on personal projects or open source, I write them on my public notes repository. For example, here’s how I kept notes while doing some CLI tooling work for my project.
Some people like to keep one large file with everything in them, I prefer splitting these running notes and linking to them when I work because it makes it easier to share them with colleagues when needed without having to clean up stuff like journaling about a great ice cream I had at lunch.
Also, if anyone ever asks me at work what I’ve been doing and how I’ve spent my time, I have a very detailed record that I can look back to.
Conceptual notes
Then I also have more general conceptual notes about software development topics like accessibility, version control, team culture, testing and so on. Each of these are usually collections of a lot of links for good articles or books I run into and my own thoughts. Each one is bit different looking and they constantly shapeshift as I learn more.
Some of these don’t even have any content themselves but act as a backlinks hub in Obsidian. My note for software testing is empty right now but it contains dozens of backlinks from other notes so I can find them through it when needed.
Other remarks
My notes are very practical oriented: I have very little notes that are purely about theory, although sometimes I do create those to accompany my other notes.
As I mentioned, in addition to building software, I also write a lot (blog posts, newsletters, conference talks, documentation) so I use my notes to collect material and work on ideas so that they can be helpful for writing.
For example when during development, I learn something new, I often write a generalized example of it with links to documentation, non-company/product specific examples and so on, so I can turn them into published writing easier later. That might not be a value for someone who doesn’t write in public.