WTF Dial: Re-evaluating the Domain

After publishing the previous post announcing the WTF Dial project, I received a lot of feedback on the associated pull request about the project definition and model from Peter Bourgon, Marcus Olsson, & Egon Elbre. I’ve done some revamping so I wanted to write a quick post to catch everyone up.

What is the WTF Dial?

Initially I thought the WTF Dial was a way for a manager to see the overall health of a team by aggregating WTF levels from all users. However, Peter Bourgon’s thought was that a manager could see the individual WTF levels of each user and have a dashboard to see them all.

Design implications

In my initial design, I avoided the term “dial” since I thought of that as the input device and not the underlying data so I used the term “gauge” instead. Unfortunately, everyone found that term confusing so it’s been changed back to “dial”. Also, the gauge was meant to be an aggregate of various user inputs and with the new design there is no aggregation so the “user input” type was dropped.

After further discussion even the idea of a “team” was not well understood. A dial might belong to multiple teams. For example, you may have a cross-disciplinary team or you may want to group just the QA folks on a team or you may want to also group at a higher level such as a department. At this point we are dropping the idea of a “team” and revisiting it later.

Skipping steps

One critical flaw in my original post is that I left out many implicit steps that I do in my head. Egon pointed out that from the standpoint of the reader it seemed that I developed the domain model in isolation. I totally agree so I’d like to clarify some additional steps I use while developing the domain model.

To say there are a lot of approaches to software design is an understatement. There are ways to manage process, requirements gathering, domain modeling, etc. The primary goal of this blog series is about code organization in Go projects so I don’t want to get too deep into higher level software design but I do want to touch briefly on my approach.

I abhor the formality of process

I am not a fan of overly formal software processes. I’m not saying the ideas in those processes don’t work but the formality of process adds confusion. The problem I see is that most people on a team understand a small subset of terms in processes like Agile or DDD and these terms tend to get misused. Terms like story points and epics also abstract more concrete ideas and make it difficult for people to get a handle on a project.

The approach that I’ve found to work is more simple:

  1. Informally discuss the project with people involved — either one-on-one or in small groups.
  2. Determine a minimum viable product (MVP) to start with.
  3. Bounce back and forth between the abstract domain model and the end UX in my head or on a notepad.
  4. Iterate by building code and getting feedback.

Admittedly, I did a terrible job with step #1 on this project. Peter helped refine the idea and he helped restrict the scope even further which improved step #2.

For step #3, I don’t have a good process I can articulate. I’ve worked on a lot of software projects over the years and read a lot of projects’ source code and I use those experiences to abstract layers during design. In this project, I knew the end UX would be some input device to set the WTF level — perhaps a physical dial or even just a command line program. The UX for the output might be a web page or a term-ui dashboard. My plan is to communicate with a server over HTTP and then persist the data to BoltDB. We are avoiding user sign up/sign in by authenticating against GitHub.

Using my favorite minimalist design tool, Monodraw, this is what the architecture looks like:

Validating the UX against the model

With this architecture in mind, I try to refine the domain model to fit within the different applications involved:

  • The command line app, wtfctl, need to authenticate the User and set the current value of a Dial.
  • The dashboard app, wtfdash, needs to display a list of Dials. Since we removed the concept of a team from the domain model, we’ll just hard code the dial identifiers for now.
  • The server, which holds the data, will authenticate Users against GitHub and manage Dial state in BoltDB. We’ll require authentication for a user to update their dial state but for now we’ll let anyone read dial state.

Final note

Building an application in public is a interesting experience. Scott Mansfield sarcastically commented, “An app built by committee? This ought to be fun.” It has been fun so far but also a bit challenging. Software, as an industry, is relatively young and there are still a wide variety of opinions about how it should be done. I think the feedback is extremely valuable.

This project is meant to show how I personally design software. It might seem the wrong way to some people but I’ve found it works well for me. As such, I’ll take in feedback and make the decision about including it or not. At the end of the day, it’s a messy process and I’m sure I’ll make mistakes along the way. Fixing design decisions is part of that process and I think it’s valuable to include that in this series as well.

Send me feedback by commenting on this post or hitting me up as @benbjohnson on Twitter.