Too Many Guides


Team-Driven Developer

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

Have you ever wanted to explore a new place? Maybe it’s an international destination or a wilderness area you haven’t had a chance to visit yet.

In your preparation for this adventure, you’d likely investigate the possibility of hiring a guide. Maybe it’s a tour guide to show you the secrets of a new city, a backpacking expert to safely take you through the backcountry, or a digital “guide” for a park you are visiting.

Whatever the case, guides can deliver a better experience wherever you go.

But there are cases when a guide doesn’t make much sense. Building software is one of them.

I think we rely too much on guides. Instead, we need to be focusing on building trails.

Let me share why.


Team-Building Exercise

For Team-Building this week, ask your team what they think of your wiki. Is it well-organized? Do your docs help people accomplish their daily work? Do you have outdated guides that need to be reviewed?

After talking to your team, look at the analytics for each page your team owns. When was it last viewed (besides yourself a few moments ago)? When was the last time it was edited? Who tends to look at it if it has regular viewers?

Then, develop a plan to build at least one "trail" through your documentation. It doesn't need to be too long, either. Even consolidating existing guides into a singular page with links to each step of the process can be a huge win.

At Vouch, we recently did this for service deployments. We consolidated all of the various How-To guides and laid them out very easily so that any engineer wanting to get their service into production had a trail to follow. We've already seen this guide cut down times to get services to production, but also less churn and frustration with the process.

Keep doing this iteratively for a while and you'll see your docs become more helpful and more easy to maintain in a few short weeks.


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 Building Custom SaaS Web Apps

Building Custom SaaS Web Apps

by Thomas McGee

I’m a web developer by trade, but I’m a creator at heart. As such, I constantly find myself making, designing, and coding new things to make life easier for creators of all kinds. Whether it be Radarist for managing your projects and tasks or Startboard for easily organizing your web bookmarks—I’m here to make it easier for anyone to earn online.

Image for Build It Better Newsletter

Build It Better Newsletter

by Jonas Fleur-Aime

Creating great software is not just about completing new features faster, submitting more pull requests, or fixing bugs. Every Wednesday I publish tips and tactics to help you meet tough deadlines, tackle tech debt, handle scope creep, manage stakeholders, make sure you're building what customers actually want, and more. I'll draw on what I've learned after spending 15 yrs as a software developer, Engineering Manager, CTO, and startup advisor.

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 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...

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...