Jonathan Thaler wrote Software Engineering is a learning process, working code a side effect where he discusses the primary purpose of software engineering. As an industry, we primarily see our role as the creators of code. He argues that code is only a side effect of the true purpose of software engineering: learning the problem domain.

It is entirely possible to find solutions to business problems that require no technology at all. I’d state it like this:

Early on in high school English 10, our class asked Mr. Robertson how we should handle a particular assignment. His response was simple:

“Do what you think an ‘A’ student would do.”

It was a frustrating answer for those too used to the rigid structure of the public school system. For others - those with a little imagination - it was freedom. It was the open road, but with guardrails to keep us from dropping off the side of a mountain.

I was lying in bed with my laptop lamenting this newsletter. It’s usually pretty late in the evening when I write this, and it’s generally due to a lack of ideas on what to write. Unfortunately, I haven’t gotten to the point of having a queue built up to give myself some relief.

My wife suggested I let myself off the hook and take a break for a day. “But that will break the chain,” I replied.

The chain I refer to is Jerry Seinfeld’s Productivity Secret. According to the story, a young comic asked Jerry Seinfeld for advice. Seinfeld’s advice was to write better jokes. To write better jokes, he said, you need to write every day.

I stumbled on a Twitter thread by Ross Kaffenberger, a senior engineer at StitchFix. He discussed the need for diagrams in software engineering, especially in larger organizations where an understanding of the entire system can’t live in a person’s head. Or even in the heads of multiple people.

When my career started, it wasn’t uncommon to have 3-ring binders filled with hand-drawn flowcharts outlining system processes. These were designed before the code, not as documentation after the fact. To me, having diagrams feels like a no-brainer.

I was thinking about a project I wanted to work on as a portfolio piece. I wanted to do all the “right things” to show off my abilities across the board, from design to development. Gathering requirements is something I haven’t done in an “official way” in a while, and I wasn’t quite sure what the kids were doing these days.

UX for the Masses has a nice list of UX documents. It turns out I’ve used most of these in one fashion or another over the years, so I’m not as out of fashion as I thought.

Having a sample of all the documents one might use in determining the scope of a project is great, but there isn’t any organization to the list. Where do I start? Which documents are better when created after a different one?

Luckily, I stumbled across an image on Pinterest that outlines the design process and lists the documents to use along the way.

Failed software projects seem to draw a certain amount of schadenfreude in our industry. It’s because we’ve all been there. Our reputation for projects that fail is so strong; it seems to elicit the question: “What’s wrong with those software developers?”

According to Tom DeMarco (co-author of the seminal book Peopleware), there is a reason for many software failures. In his experience as a technical expert during software litigation cases, failure happens for one reason:

Writing this newsletter this week has been difficult. As I struggled to find topics to write, I turned more than once to my Evernote archives. I have plenty of ideas from which to choose, yet I keep scrolling. It’s a drawback of my top strength: input.

I’m great at collecting information I may find a use for later. But it can also lead to “analysis paralysis.” More input or more opinions - either can bog down your decision making.

A good way to be unsure about something is to ask for one more opinion. More opinions often lead to indecision, not clarity. If necessary, ask for a few, add your own, make a call, and move on. Nearly all decisions are temporary, but stalling is permanent time lost.

— Jason Fried (@jasonfried) January 22, 2020

Software development is an exercise in refinement. As we develop software, we make decisions that affect the outcome of the project. For example, we decide our project needs to store data. After investigation, we determine a traditional database would make the most sense for this project. We choose MySQL. Next, we create the tables we believe the software needs, and then the columns to represent the data. Each decision brings the project closer to its final form.

Not having the answers to these decisions is why it is so difficult to create software estimates. We develop estimates made on assumptions, but those assumptions are invalidated by the decisions made along the way.

If the estimate assumed a document-oriented database like MongoDB was appropriate, it is invalid as soon as we decide to use a traditional database. Once this decision occurs, it is up to the project manager to support the change and trigger a re-estimation. Good project managers will be able to navigate a project to successful completion through reasonable project control. As long as the project is about the right size and meets most of the requirements, it “meets the estimate.”

This article now lives at Career Documentation

Gergely Orosz wrote a fantastic piece on his blog: What Silicon Valley "Gets" about Software Engineers that Traditional Companies Do Not. In it, he makes the argument that traditional companies look at developers no different than factory workers, except they produce code instead of widgets. On the other hand, "Silicon Valley" companies expect their software engineers to solve big problems, and are therefore involved in discussions with people outside of engineering. Their ideas are also valued and can lead to big opportunities for the company.

One of the reasons I've worked in small companies for much of my career is getting to work with the business. When there are so few people in the IT team, there aren't the layers of bureaucratic "protection" between developers and the business.

On the other hand, there's a drawback to the small company development teams: they're stretched too thin. There's always more work to do than they can accomplish. It's a trade off, since small companies can't afford the big teams Silicon Valley companies can.

This post has moved to Late Projects

As I’ve been looking for my next role, I’ve wrestled with the question of going back to being an individual contributor (i.e. a developer) or to continue on the track of technical leadership I was pursuing the last few years.

A friend recommended I read “The Motive” by Patrick Lencioni to help guide my thoughts on the question. Written as a fable, “The Motive” tells the story of two CEOs in the same industry and the advice one offers to the other.

One CEO (Shay) is worried about his job and the ability of his company to continue to grow. The other CEO (Liam) is leading a successful company in a nearby market and starts to mentor Shay about what it means to be a leader.

As the story unfolds, it becomes clear that Shay has been motivated by the title, salary, and perks of being a leader, but has fundamentally failed to lead his organization by doing the hard things leaders need to do.

It hardly seems the right time to write about tech topics when seditionists stormed the Capitol building to interfere with our democratic processes.

So instead, I can only express my thoughts today:

Listen to one another. Be empathetic. Be kind. It's okay to have a difference of opinion, but it should not stop us from treating each other with dignity.

In her 2019 dotCSS presentation, Sarah Dayan makes the case for creating Utility-First CSS.

Utility-first CSS focuses on creating classes that describe how something should be rendered in the browser, rather than creating a class to represent the component being rendered and attaching all of the CSS code required to the class for that component.

For those already familiar with this strategy, it is how Tailwind CSS was designed. I haven't had the opportunity to use Tailwind, and frankly it was low on my list to learn for some reasons I'll outline below.

First, a comparison of the traditional "component" way and the "utility" way:

One of those things I miss from the pre-digital era is the concert ticket stub. There was something about getting the pristine ticket in the mail or at the box office and anticipating the fun that will be had each time you walked past the tickets stuck to you fridge with a magnet. Then after the concert, you'd pull the ticket from your pocket, creased and bent and add it to the collection of stubs.

Sadly, with online ticket purchases you no longer get the ticket printed on card stock. Printing the ticket stub on your printer just isn't the same. It's a lost art form.

Now it seems the ski lift ticket is going the same way as the concert ticket. Instead of a tine over which you fold your ticket, ski resorts are now issuing RFID cards. The cards are used to pass through an electronic gate after getting scanned.

It's a technology in search of a problem.

For many years I took a tip from Chris Brogan and set “3 Words” as a direction for yearly goals. It was a great way to set up a vision for the year.

But then life happened - between work and a teenager playing high school and travel lacrosse - and I dropped setting goals altogether as being a parent was the top priority. No regrets.

This year I thought I would steal a single phrase from James Clear instead of three words:

— James Clear (@JamesClear)

The worst development situation I ever stepped into was an IT department where the five year old production code was completely documented. Literally NO documentation.

Our team of three all joined within two months of each other after the entire previous IT department left the company. We had to document the system via debugging production bugs and tracing through code manually because there were no unit or integration tests to work with.

It reminds me of a tweet from Leon Bambrick:

— Leon Bambrick (@secretGeek)

Or happy Friday if you’re not into celebrating Christmas.

As a Christian, I celebrate Christmas to honor the birth of my savior, Christ Jesus. But I also love Christmas because it’s a time for fellowship, thankfulness, and family.

I hope your holiday season is filled with joy despite all that has happened this year. Be blessed.

(No post tomorrow, talk with you Monday).

Technical debt, in its original definition by Ward Cunningham, is the gap between the software that developers built based on an incomplete understanding of the problem. The time making updates to correct the misunderstanding is the technical debt.

In the Manager's Path, Camille Fournier recommends teams:

“...dedicate 20% of your time in every planning session to system sustainability work (“sustainability” instead of the more common “technical debt”).

Sustainability work is a much better term than technical debt. With so many negative connotations about the word "debt", and a tendency to write poor code under the technical debt moniker, the term should be retired.

Three questions to ask while leading your team:

• Where are the bottlenecks that are slowing us down and how can I eliminate that friction?
• What can I do that will make the development team better in the next month?

In the software world there is a strong idea of finding rockstars and ninjas - the so-called 10x developers. These are the near legendary developers so powerful they accomplish ten times as much as a regular developer.

The problem is, many of these 10x developers tend to also be cowboy coders:

Cowboy coding is software development where programmers have autonomy over the development process. This includes control of the project's schedule, languages, algorithms, tools, frameworks and coding style.

A cowboy coder can be a lone developer or part of a group of developers working with minimal process or discipline.

source: wikipedia

Because they work so fast, quality, documentation and cross-training often take a backseat to their late-night, caffeine-fueled programming sessions. It can really hurt the development process.

What do you do when you have to remember some bit of information that used a couple of weeks ago?

For me, remembering a quick snippet of code, a URL, or a database query that I used to accomplish a temporary task is nearly impossible.

But retrieving that information again has come in handy time and time again. To solve that, I created a file on my computer desktop.

I call it scrapheap.txt.

Eleventy is one of the sparkly new generation of static site generators. As a technology, it takes markup and compiles it (mostly at deploy time) into the static pages that can be quickly served to the user.

Unlike something like Gatsby (from my understanding), Eleventy doesn't do anything like rehydrating pages or pulling in information from APIs (mostly).

I see it as the true bare-bones - yet powerful - static page generator. For things like blogs, I don't have a need for anything more than a static site, so Eleventy is the perfect solution.

Pages built from Eleventy can be created from html, markdown, javascript, and other sources. It's agnostic about what source the content comes from.

It’s probably no surprise to anyone in the know that the followup to my email about Netlfy would most likely be about Jamstack. After all, Jamstack was created by Netlify.

Jamstack is an architecture that improves the speed, security, and scalablilty of websites.

While writing my last post about Netlify, it occurred to me that while it was beneficial to know what it was at a high level for my own educational purposes, I did not really think about the technology as part of a solution specific to a project or organization.

That led to my thoughts about what questions I would ask when assessing a new technology.

• What key business problem (s) will this technology solve?

"Everyone" in the circles I follow seems to love Netlify. I haven't used it but want to learn more about it. Here goes...

Netlify has been around since 2014 and was created because of the trend toward git-based deployment as well as static site generators[1]. It is essentially a serverless backend for websites.

According to their website, setting up a Netlify site and delpoying it is as easy as:

1. Connecting to a git repsository.
2. Creating build steps.
3. Deploying.

Ryan is the VP of Creative at HUDDL DESIGN. They’re a startup creating amazing designs from acoustic panels for interior spaces.

Recently he told me how amazing it is working with his partners because there isn’t a sense of ego or politics. He shared an example with me (and which I share with his permission):

He was putting together a RFP, but was struggling with “designer’s block”. He had ideas for the pitch but couldn’t quite get started. Ryan openly admitted that to one of the other partners. Even though design is his area of focus, his partner hopped on a video call and they brainstormed ideas - even going as far as creating some ideas in Powerpoint as it was the easiest tool for both of them to collaborate. Together they pushed past the block and Ryan did amazing work on the final RFP presentation. (I saw it, it was very cool ;-)

One small utility I love (Windows only) is PureText.

This little tool sits in the dock and provides a fast way to remove all of the formatting of something you’ve copied to the clipboard.

While it’s running, I know that hitting CTRL+SHIFT+V will remove anything from the text and paste only the text itself.

This article now lives at RACI.

Communication is critical in organizations and on project teams. If I can learn something than improves how a project runs, I’m all for it.

One thing I learned is the RACI method, or RACI matrix. As a communication tool, it allows teams to understand who is responsible for what.

Responsible, Accountable, Consulted and Informed

Derek Sivers started the idea of a /now page to keep visitors to personal sites to date on what’s going on. It came about because an /about page doesn’t really describe what a person is up to, and digging through social media is too in the weeds to be useful either.

It occurred to me that I created a document of my own I called “The Plan” and it was a lot of what I would consider to be a /now document. Here’s my stab at it; I’ll likely turn this into a page on a site somewhere/sometime. I’m keeping it career-based for now.

If you’d like to see more /now pages, you can visit Derek’s nownownow site.

Now

I was talking to a recruiter today, and he mentioned that his company is switching to using Kafka for a lot of their systems. To be honest, I have heard the name Kafka, but had literally no idea what it was. This was an unknown unknown to me until today. I decided to learn a little bit about what Apache Kafka is.

According to TechBeacon, Kafka is:

I’ve been writing this newsletter in the evening when I finally get around to it and sending it out as soon as I finish a quick edit. (Can you tell? lmk)

Tonight something came up that will replace that time I’ve been using to write. My first thought was “I’ll write this later”, but honestly it’s Friday, Teh Wife is winding down from a busy week and then there’s the Mandelorian and bourbon. So the truth is if I said I would write later, I wouldn’t. I’m lying to myself.

Consistency is a tough thing to stick to.

NaNoWriMo is a month-long sprint to write a novel in 30 days. This year I started strong, but the effort was too grand (and the plot too thin) to keep at it. So I stopped writing. But what would have been better than burning out writing 1667 words every day was to write 100 anyway, whether I felt like it or not.

This post now lives here: How To Write a Bug Report

Network Up

Most software developers are already hesitant to network, so this is more difficult than your average “Network More”advice.

Networking with peers is fine but the ability to network one or two levels above your position is going to give you the most benefit in your career. Most individual contributors - your peers as a software developer - aren’t going to be the hiring manager when its time for you to get a new job.

Instead, your goal should be to network with those who will be the hiring managers in the future when you’re seeking your next opportunity. If you’re early in your career; team leads are a good place to start… their careers will grow over time. Engineering Managers will move on to other positions as Directors, so getting to know them and keeping in touch will also be useful.

Back in 2017 I created a new note in Evernote called "Learning Path". It was intended to be an outline of things I wanted to learn, and a way to organize all the saved notes from around the web. This summer, when I had some time on my hands and needed to clean out my Evernote "inbox", I added a whole bunch of topics to the Learning Path. At this point, it's 16 pages long!

While there are many things to be refined and reorganized in that list, I need to start taking stabs at learning what's in it.

This newsletter, Known Unknowns, is the output of digging into the Learning Path. Topics are things I know I need to learn more about. Over time, Unknown Unknowns - the things I don't even know I don't know - will get added to the list as well.

The topics will cover software development, personal development, leadership and maybe an occasional faith email too.

Yesterday I wrote about my deck staining project and how it, like software projects, was spiraling out of control. I mentioned I would make some comparisons to software estimates, but I don’t have the book I planned to reference with me. Oops.

Scott McConnell’s Software Estimation: Demystifying The Black Art covers a number of factors that can swing a software estimate greatly in different ways.

Here are three factors which affect the outcome of a project estimate:

Expertise of the team

Nothing is worse than a project that takes longer than expected. I've been staining our decks, and the project is going into its third week already. Now, I've stained decks before, so I have a rough idea of how much stain I'll need, what kinds of brushes to use, what I will need to tape off in order to keep the stain where it needs to be.

Yet this project persists...

The first thing that made a change to the known scope for the project was changing from ugly aluminum balusters to wire cable for the spaces between the railings. It looks easy based on the YouTube videos by professional deck builders, but the cost of the project quadrupled immediately with this decision. The effort remains to be seen, since the installation will be the last step.

The project had other unknown scope that creeped in as well. A thorough power wash took a lot of time, and when that was completed I realized how rough the condition of the wood was. This led to 3 rounds of sanding followed by applying brightener to the remaining wood and another quick wash.

Yesterday I discussed some thoughts I had about learning Python, especially around some scripting to create notes in Evernote since IFTTT would no longer suit my needs.

Today I explored Python a little more closely, and it doesn’t seem to be that complicated of a new language to learn. Caveat: almost all languages are easy to learn, it’s the libraries and frameworks that can suck the life out of you.

One though that hadn’t occurred to me, even though I hinted at it yesterday, was that I could use Python to create scripts to do things. My thought at the time was to use it on a server (probably in a cron job), but some of the power I wasn’t considering with Python is in creating scripts to run on my local PC to do different things.

Having done some PowerShell scripting in the past, I can see this being very similar, but without being tied to Microsoft’s scripting language. (I’ve put aside my frustrations with Microsoft from years past and wholly support their developer ecosystem, but it’s nice to have choices).

A couple of roles I’ve been talking with hiring managers for have been outside the .NET ecosystem I’m most familiar with. In particular, two are codebases in Python.

Steve McConnell, in Software Estimation: Demystifying the Black Art, states that developers working in interpreted languages can be up to twice as productive as those working with compiled languages.

Python looks like the next language for me to learn. There’s great support for it on devices as small as Raspberry Pis, and its pretty commonly used in scripts running on severs.

-

Starting a new job should never fill you with such anxiety that you start to get imposter syndrome.

With all the new code, environments, clients and TLAs that are second nature to those who have been on the team a while already, you can’t expect to step in and feel like you know what you’re doing.

It’s not competence you’re missing, it’s context.

I’ve been brushing up on some system design, and found a great YouTube channel by Guarav Sen. He explains all kinds of algorithms and technical System Design features.

I learned from Austin Kleon that writing notes in the margins of a book is a fairly common habit, and that it has a name: marginalia.

Other than the Bible, I've always struggled with the idea of marking up a book with my own thoughts and ideas. To even underline some text with a highlighter makes me nervous. And my subsequent readings of a marked up book always feels less special, as if I've used up some of the ideas with a yellow pencil.

This is partially why I'm now doing sketch notes of some of the non-fiction I'm reading. This is a horribly slow process, but I do feel that I'm thinking about the text as I render it, and that is the point: to learn from what I read. It's too easy today to simply skim an article and not put any thought into it.

Slow down, learn more.

“The greatest way to make progress is to keep moving.” - John C. Maxwell

I lost my newsletter draft that I thought I had scheduled to go out Monday. Today I don’t feel like I have anything to say, but this quote inspired my to write this little bit anyway.

I was feeling a little lost the other day, kind of holding a pity party about my skills and abilities. My wife encouraged me to take the Clifton Strengthsfinder to better understand what my skills truly are. The test is pricey ($50 USD), but so worth it!

You answer a series of 177 questions where you are presented with two options. You select on a scale of 5 whether you agree with one or the other options or are neutral in the middle. The test takes about 20 minutes to complete and the test results are ready immediately afterward.

I. Was. Blow. Away.

I didn’t think the questions pertained to much of anything, and sometimes the choices didn’t even seem like opposites. Yet the results pegged me perfectly.