Software Engineering Notebook

Do you keep a software engineering notebook or log book? If not, you may want to consider doing it. Below, I outline what I've been doing for many years and how it has helped me. (Notebook, Log Book, Field Notes, Lab Notebook, Journal?)

First, I refer to my notebook as a software engineering notebook, rather than a programming or code journal because I try to encourage myself to be systematic, or scientific-lite about it. Meaning that I have a general collections of sections that I have developed which encourages me to have a structure to the information that I capture. It helps me remember to capture certain aspects of the things I'm learning or experimenting with. For example, references for the information I'm writing.

Second, my interests are broader than just "programming" or "coding". I love all aspects of software engineering! I love the psychological UI/UX color, typography, animation aspects of applications as much as I do building out CI/CD deployment pipelines, as well as building the application itself. In my notebooks over the years, I find all of these topics covered in various and interesting ways.

Engineering has been defined in Merriam-Webster as: "the design and manufacture of complex products". The Wikipedia universe currently defines "software engineering" as, "the systematic application of engineering approaches to the development of software." It may also be my degree in aerospace engineering, that encourages me to approach this from a more scientific approach. But, there are no hard and fast rules for your own software engineering notebook. I'm going to share what I've done and you might adopt it for a while until you decide on how you want to change it up and make it personal for yourself. My format is not rigid and it is never "done"; it is forever changing in ways that I want to experiment.

In the past, however, I kept my software engineering notebook to myself, usually on my personal Atlassian Confluence Wiki. It's not pretty, but my notebook is just for me. But, I now realize that there might be times when my notes might be helpful to others. So, I'm trying to migrate it to a more public format by using this Ghost blog.

My goal, however, remains the same - to capture notes for me. If they help you, great. If they confuse you, I'm sorry, I may try to help you understand if you contact me, but then again, I'm busy with a lot of my own projects and I may not have time. Again, these notes are for me.

Typical types of pages that I keep in my electronic notebook: Experiments, Course Notes, Future Blog Topics

Experiments:

While I am learning something new, or trying a new approach, I like to treat it loosely as an experiment. I like to capture the following as I'm experimenting:

The "title": I often find that as I work through the problem, the title I originally assigned often morphs (becomes more specific) as I develop the solution. Naming the problem, like naming variables and functions in software, is often a challenging part of solving it.
The "problem statement": More explanation of what I'm trying to accomplish, what I want to learn, the question I'm trying to answer, etc.
The initial conditions and assumptions that I'm making.
The experiment itself: Documenting where the code (Git repo) and data lives, the commands I'm issuing, and the results I get. I leave these in to show the chronological progression of my study. Rarely if ever do I delete them. I often include inline code blocks of command line commands, the results just get copied and pasted into the notebook. I've found that many times as I progress through my experimentations, I misinterpreted the results and being able to review the chronological progress at how I arrived here, I'm able to find the error.
Doing this also allows me to learn to diagnose these errors earlier. For example, how the operating system was trying to tell me one thing, but I misinterpreted it which lead me to an incorrect conclusion or a new hypothesis that I later proved wrong. I also include screenshots of the browser developer tools (e.g Console) output to show the results.
In addition, as I progress, I usually develop additional hypothesis, or experiments to try - while I'm working on the current experiment. So, I capture all of these as I go. Some I may get to, others may live on until another day. Again, these notes are just for me.
Lessons learned: If the topic is sufficiently large or long, I will often summarize "lessons learned" at the top of the topic so that when I return to it, I have my own Cliff Notes (or abstract) for the topic. Tailored to what I didn't know and therefore were a gap.
References: I also include links to blogs, books, and conversations used to develop my understanding of the problem, possible approaches, and results that others have obtained.

Course Notes:

When I take a course - Udemy, Pluralsight, Coursera, O'Reilly, etc, I take a lot of notes.

It helps me focus on the material rather. I also take screenshots of the lecture material or website information I find.
It helps me understand ideas and connect them with concepts from other instructors by making hyperlinks to other entries and discoveries I've made.
It helps me retain what I learned, not only because the act of typing up the notes, helps make additional connections to other ideas, but it also allows me to return to it and scan it for the things that I didn't know.
It helps me clear that stuff out of my head knowing that I understand the concepts and I can get back to the details at any time reliably.

The format I use is pretty simple (and although I'm biased) quite logical:

Course title
Author
Date the course was released (or last updated)
Date I started the course
Lessons learned (summary)
Chronological notes of each section; bulleted highlights

Blog Topics:

This lists the proposed idea, a couple sentences that could be compared to an "abstract", and the date I entered it.

References: