Sometimes the Struggle is Bad Writing

After years of learning new things in fields like business, law, and software I have learned that the biggest variable in understanding something is the quality of writing and communication. Communicating well is hard and in technical fields not enough value is placed on good writing. Communities like Ruby are lucky to have folks like Michael Hartl and Sandi Metz that are gifted with the written word. All things being equal I will typically choose a tool or programming language that is better documented than one that is new and shiny.

When I was faced with some legacy code bases at MAPC that felt bad I struggled to articulate what was bad about them. It took more than a few hours of Googling to discover Martin Fowler’s concept of code smells. These code smells provided a menu of issues that might exist in a code base along with recipes for refactoring away these issues. If you do not have the right vocabulary you will struggle to communicate. If your audience consists of experts you can assume a shared vocabulary and knowledge base, but if your audience is not then you need to start from the basic concepts before explaining the more complex things.

If you are a beginning software developer the best two things you can do are to find good writing about software, and to try and teach what you have learned to others. By getting experience in communicating new concepts to other software developers you can see where your ideas and metaphors fail. You can also better articulate the reasons for why you do things in your programming language. Communicating what you are doing well not only helps you write better code, it helps you identify good writing yourself which makes learning new things easier.

The Backlog

The other day one of my co-workers mentioned that she feels like she has a lot of free time in her life. This is one feeling that I struggle to relate to lately. I have been working to try and liberate time where I can. Despite doing this I can tell I am still a bit behind on the basics. My email inbox still needs to be tended. I blog a few times a week instead of every day. I am not able to do everything I want and it is tough.

The two big items in my life are my day job at MAPC and Code for Boston. Next to that is my training for a half marathon. Once I have carved out time for those things I also need to make sure I am still talking to my friends and family. I have a backlog of games on Nintendo Switch that I am working through, most recently Super Mario Odyssey. I am reading a couple books including the latest Dan Brown novel and an introduction to the Swift Programming language. This is to say nothing of the Arduino kit sitting in my drawer and books I have not started yet.

One way I have liberated time is to get an Instacart subscription. By removing the need to travel to the grocery store every week I save about two hours which I can then use towards doing other things I prefer. Even when I’m waiting at home that time can at least be more useful than wandering the aisles of the grocery store.

Time is our most precious resource so I try and think of ways to better spend it doing the things I like to do instead of the things I need to do. It is challenging to fit everything in, but the main thing I have learned is you do not find time, you usually end up making it. Each decision to do something is a decision to not do a bunch of other stuff. By doing the right things you can later liberate more of your time.


By far the mode of receiving information that I find most challenging is the meeting (actually the conference call is a bit worse). Lucky for me government runs mostly on meetings and I now attend a lot of them. As evidenced by this blog my home field for communication is writing. When I have in-person conversations I often later forget things or I miss details. Despite all my efforts to avoid meetings and communicate that they are a terrible method of communication for me, it is challenging to teach old dogs new tricks (in this case the “memo” or “note”).

At MAPC I attended a facilitation training lead by a couple of our long time agency employees. This training provided a framework for running a structured meeting that valuably relied upon a written agenda. It also dispersed responsibility so that a person has to keep time and take notes. This dispersal of responsibilities allows most of the attendants to better focus on the meeting itself. They know how it will run and have a structure before hand with notes afterwards.

When I am in a meeting that is not run in this manner I usually bring my iPad and attempt to take notes. The challenging part of doing this is that my focus is divided between the effort of note taking and actually thinking about and contributing to the meeting content. Overall this is not optimal, but I have found it to be the least worst approach.

For the most part my attendance at meetings, given how challenging I find them, is not usually for my benefit but for the benefit of other people whose styles favor verbal communication over written communication. Otherwise I use them mostly as an attention focus mechanism. In a world where people can easily shuffle around their own work and priorities, scheduling a meeting is a good way to force them to focus on something. Also having a regular check-in about a project is a good accountability mechanism that sets a rhythm for progress.

React and Jekyll

I have been spending my past week at work learning React for the purpose of making an interactive website and overall have found it to be one of the easier Javascript frameworks to master. A key component of this is React has well written documentation. Despite the complexity of the concepts, they are fairly well explained. Given the current popularity of React there are also plenty of third party resources and StackOverflow posts on React related topics. It is clear that React has the wind at its back.

For most of our static websites at MAPC we use Jekyll. Some Googling found this helpful blog post about setting up React with Jekyll. However I learned of an even better trick with this setup. Once you setup webpack you can run ./node_modules/.bin/webpack --watch and the bundle.js file will be updated every time you make changes to the files in your webpack directory. Furthermore you can run jekyll serve --live reload and connect Safari to jekyll’s live reload server so your browser auto updates changes as you make them to your react or Jekyll code. This greatly speeds up the development process.

Learning React and spending more time in Javascript land has also lead me to identify and empathize better with the challenges others face when learning new languages and frameworks. The abstractions are not yet memorized. The scope of variables is not always clear or understood. You are constantly looking up method names and syntax. Your debugging toolkit is often not established. It’s like going into a new country, having to drive on the other side of the road, and figure out how to convert everything from metric.

Ultimately I think learning this will be worth it. It will give me flexility to create new features in user interfaces. It will help me better understand some of the excitement and challenges my peers doing front-end web development at Code for Boston face. It will also let me play more with the WebKit Web Inspector to better understand why certain web pages render so poorly when I browse the web.

The Elevator Pitch

One of the biggest challenges of my work is communicating it. Both at MAPC and Code for Boston we do a lot of things that people do not have foundational knowledge about. When I meet people outside the technology industry for the first time and describe what I do, they need to have some kind of foundation in about thirty-seconds or they are going to get lost and confused quickly. They need the elevator pitch.

The interesting thing about the elevator pitch is first getting the reaction of someone to it. Did I land it with my description? What is their first thought or question? A lot of times they do not even know what question to ask. Often it takes me giving an example or two of one of the projects that I have worked on until they understand my work.

Once I explain I work with algorithms people often see their interest peaked. Artificial intelligence and algorithms are two topics from technology that have permeated mainstream culture, but people are still struggling to figure them out. Are they really going to kill us? Will they take all the jobs? There is definitely a sense of caution and fear. The dry and mechanical attitude I see at data science conferences is quite different from the attitudes I see when I talk to lawyers and others studying them. Algorithms and artificial intelligence are going to greatly impact what machines can do, but industry is doing a poor job of communicating what the impact really will be.

Talking to a group of folk that are not inside the tech industry last night gave me a chance to evaluate how I talk about algorithms and AI. I like to talk about how we built our Youth Match algorithm with young people to help them. I am sad I did not think to explain to my fellow law school alumni that lawyers will be the ones buying algorithms and other technologies for local government. They are going to need to understand these things because they are going to impact the citizens they work for. Hopefully I do a better job of remembering that part of the story at my next event.

Follow posts: RSS Feed
This work by Matt Zagaja is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License.