The Agile Manifesto suggests making decisions as late as possible. Agile favors:

• Customer collaboration over contract negotiations

What is the purpose of software engineering (and software engineers)?

My golden rule of software engineering: our job as engineers is not to turn product specs into code. Our job is to deliver the maximum value for the company at the lowest cost.

Rod Begbie,

This Kit Kat ad pretty much sums up people's workdays. When we worked in offices, there was a limit because only so many conference rooms were available. Virtual meetings get scheduled with abandon.

Here are a few tips on how to make meetings better.

Speedy Meetings

User scenarios describe the changes in the system’s state:

• A “given” statement is a precondition. It describes the past state.
• A “when” statement is the current event. It is what is happening now.

Believe it or not, this is issue 50 of Known Unknowns. If you’d like, you can check out the archive.

My request of you, dear reader, is to reply to this email and let me know what you think of this experiment.

Test-Driven Development (TDD) aims to test small bits of code using the Red-Green-Refactor pattern. First, write a test that fails (Red), then write the most straightforward test that passes (Green), finally refactoring until the code is as clean as possible.

Behavior-Driven Development (BDD) inherits the spirit of TDD while using artifacts provided by project stakeholders, such as user stories. BDD uses plain-text scenarios to bridge the gap between technical teams and regular teams.

Using a tool like Cucumber, developers create tests that match these plain-text scenarios written in a simple domain language called Gherkin.

Scenario: [a scenario starting with "should"]

Given [some preconditions]
When [an action happens]
Then [a result]

Today I built a User Persona (of me).

Alan Cooper first described User Personas in his 1998 book "The Inmates Are Running the Asylum". Cooper created these personas based on interviews with seven or eight users.

"Personas are not real people, but they represent them throughout the design process. They are hypothetical archetypes of actual users. [...] Personas are defined by their goals." - Alan Cooper, The Inmates Are Running the Asylum

Kent Beck originally suggested the idea of User Stories to help define requirements with a politically neutral balance between the business folks and developers.

"Use cases as I have seen them used are complex and formal enough that business doesn't want to touch them. This leads to development asking all the questions and writing down all the answers and taking responsibility for the resulting corpus. Business is reduced to sitting on the other side of the table and pointing."

According to Kent, the goal was to imagine an artifact simple enough for non-technical teams to create and own. They would feel comfortable adding new requirements and appropriately prioritizing them.

Dan North suggested the standard User Story Template we use to express user stories:

Getting up to speed is a challenge, particularly when starting a new role with a company working in a domain in which you are unfamiliar.

Collective learning can get bogged down while you are catching up. Here are four ways to get a head start in your learning:

Do Some Research

Given a domain with an existing history, learn who the “thought leaders” are. Consume their content, whether books, blogs, or videos. They have thought about the challenging problems in the domain and may have already provided solutions. Their knowledge gives yours a quick boost.

Previously, I wrote about how Software Engineering is a Learning Process where we aim to understand the business domain for which we design software. But why is it important? There are several benefits to understanding the business domain.

User Empathy

When we understand the terminology and rules in the space, we can better understand the users of our software. Conversations are smoother, and it becomes easier to determine user needs.

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.