Improve Your Writing with Three Simple Words


Team-Driven Developer

A newsletter with tips and tools for building software as a team

Imagine reading a technical design document or RFC. As you read, you notice that the language in the document is a bit confusing.

For example:

Requests likely need to be authorized using standard HTTP auth mechanisms

What does this “requirement” mean? Are we using “standard” Authorization headers with base 64 encoded usernames and passwords? I don’t see a mention of HTTPS. And I also don’t know what “likely” is meant to convey...

The author of the document isn’t trying to be confusing, but they lack the practices and tools to help make their document effective.

A key tool that I have repeatedly turned to for help with my technical writing is RFC 2119. It’s a short one (you should go read it!) that provides a prescriptive set of terms and writing style to help make requirements and details clear.

Let's dive into how this RFC can improve your writing!

Team-Building Exercise

This week's Team-Building Exercise: perform a technical document together, post-implementation review!

  • Pick a previous technical design document or ADR
  • Pick a timeslot of about 30 minutes
  • Review the document in light of how the project went (obstacles you faced, ambiguity encountered, etc.)

The goal is to learn if there were places where the document could have been clearer or improved based on how the project went.

The point is to identify if there were significant gaps that slowed the project down or left people unsure of what to implement. An example might be that an API was described ineffectively, and a developer missed a vital use case as a result. Or perhaps there wasn't a lot of clarity on what to do in a specific edge case, and a significant amount of rework was required.

Of course, you can never fully anticipate every issue with a project. So keep that in mind as you review. You aren't trying to point out every detail that was missed.

Remember to perform these in the same way as blameless post-mortems. We aren't trying to point fingers at the author for missing a detail (the team might have failed to ask proper clarifying questions!), but rather learn what sorts of things the team should be more thoughtful about in the future.

You don't need to do this all the time, but for a project that struggled to be delivered, this can be a good tool to spark learning.


Here are some more resources from me to help you build better teams!​

  • 📕 Code Review Champion - My book on code reviews will help you become a world-class code reviewer. From giving kind feedback to navigating conflict, this book can help anyone wanting to sharpen their code review skills.
  • ❓​Questions for Devs - Building a team takes more than catching up about your weekend at standup. I've used these questions to build relationships with my team and push past the same old surface-level conversations.
  • ​📋 Pull Request Template - Maximize your efforts in pull requests by giving context right at the beginning of a new pull request. Copy and paste this template into your repo, and voilà!
  • 📊 ​Code Review Metrics - Start measuring how your team tracks against a few common code review metrics. This python script will pull your GitHub pull requests and generate a CSV you can slice-n-dice to get the data you want. It also has graphs! As this is an open-source project, your contributions and feedback would be great!

Other Creators I Recommend

Image for Looking for your next tech job?

Looking for your next tech job?

You're in the right spot. I'm Dr. Kyle Elliott, the founder and tech career coach behind CaffeinatedKyle.com, and I love giving away free resources that help to ensure your job search and career success.

Join 7,435+ fellow job seekers who have downloaded my free Job Search Launch Guide.

Image for The Mindful Dev

The Mindful Dev

Dagna is an Engineer turned Coach for ambitious professionals in Tech. She has transitioned from programming computers to reprogramming human minds. Her book Brain Refactor is a recognized Amazon bestseller, helping professionals optimize their internal programming to thrive in tech.

113 Cherry St #92768, Seattle, WA 98104
Unsubscribe · Preferences

Dan Goslen | The Team-Driven Developer

Learn the tips and tools for building software as a team! Every other week, I send a long-form article, a team-building exercise, and resources to help you build better software teams so you can build better software.

Read more from Dan Goslen | The Team-Driven Developer

Team-Driven Developer A newsletter with tips and tools for building software as a team A complex system is not the same as a system that delivers advanced functionality. Complexity within software refers to the characteristics of a software system and its ability to change over time. Functionality refers to the capabilities a software system exposes. In my experience, we often overlook this distinction more than we realize. I’ve seen engineers brag about how complex their system was as...

Team-Driven Developer A newsletter with tips and tools for building software as a team 👋 Hi everyone! Sorry for the delay in getting the latest issue out - I've had some unexpected family needs that required a lot of my time and attention, and I wasn't able to get an issue out. Thank you for your patience! Onto the issue. At some point in your career, you’ll be on a project that is running behind. Maybe the scope was bigger than expected. Maybe a few technical risks exploded. Perhaps the...

Team-Driven Developer A newsletter with tips and tools for building software as a team 👋 Welcome to all the new members of the newsletter! Glad you are here. As I’ve shared, I’m a big fan of code reviews and their benefits. Code reviews are an important part of the software lifecycle, both automated and person-to-person. They can help spread knowledge, act as a conduit for mentoring, find bugs before they make it to production, etc. Unfortunately, code reviews also have a tendency to start...