The Role of a Principal Engineer: Strategic Vision and Tactical Execution

I just wrote a post about principal engineers and the purpose of the role. I wanted to elaborate a bit more about strategic influence and tactical implementation, thus I present this post. Cheers!

In any high-performing engineering team, the Principal Engineer role is uniquely positioned to influence both the day-to-day and the bigger picture. They wear the hats of both mentor and visionary, technical architect and pragmatist. This post is a deep dive into the core tenants I outlined before—because bringing each of these to life is where the real magic happens.

Technical Vision and Strategy That Scales

Strategic Influence: A Principal Engineer’s vision isn’t just about the project’s success—it’s about aligning technical goals with business outcomes, anticipating future needs, and charting a course for scalable growth. They take the long view, ensuring that each architectural decision today supports the needs of tomorrow. This means understanding where the company aims to be in five or ten years and building systems that can grow without creating excessive technical debt.

Tactical Implementation: To implement this vision tactically, a Principal Engineer uses an iterative approach. They document the architecture, outline performance benchmarks, and integrate architectural reviews into sprints. Tactical steps might include establishing microservices where modularity is beneficial, employing a well-planned API strategy, or implementing event-driven architectures that allow scalability. They routinely assess the current state, asking questions like, “If we double our users tomorrow, will the system keep up?” Each change made is documented to create a record for future engineers and ensure continuity.

Mentorship and the Power of Knowledge Transfer

Strategic Influence: A Principal Engineer knows that knowledge transfer is a multiplier—helping others grow brings exponential returns to the entire team. Strategically, they foster a culture of learning that’s self-sustaining, turning juniors and mid-levels into future senior engineers and making knowledge retention a team-wide effort.

Tactical Implementation: They might establish a formal mentorship program or set up technical guilds where engineers can share insights and challenges. This could include weekly code review sessions, hands-on workshops, or an open-door policy where any engineer can come for guidance. For complex systems, they create onboarding guides, and for specific skills, they offer paired programming sessions. A tactical approach might also involve setting up a Slack channel for “questions without judgment” to encourage open discussions and reduce knowledge silos.

Complexity Mastered: The Art of Solving the Toughest Problems

Strategic Influence: The ability to handle complexity is part of what sets a Principal Engineer apart. They strategically prioritize problems by impact, focusing on challenges that, once solved, will pave the way for the team to make faster progress. Their problem-solving approach is about setting an example—showing the team how to approach big issues without fear or hesitation.

Tactical Implementation: Tackling complexity requires a mixture of hands-on effort and modeling best practices. A Principal Engineer might start by breaking down complex problems into manageable parts, showing the team a structured approach to problem-solving. They set up focused sprints to tackle known challenges, using tools like technical spikes and architectural proofs of concept to test solutions before committing them to the main codebase. Importantly, they prioritize transparency, documenting how they approached each problem so others can learn from it.

Cross-Functional Influence

Strategic Influence: Principal Engineers bridge the gap between engineering and every other department that touches the project. They ensure that engineering decisions are in sync with product goals, customer feedback, and operational realities. This cross-functional strategy helps the organization avoid misalignment and costly reworks.

Tactical Implementation: Tactically, this means facilitating regular cross-team sync-ups, participating in product planning meetings, and perhaps even joining customer feedback sessions. A Principal Engineer might create integration documentation for customer support or collaborate on a “feature release” plan with product and marketing. By fostering open communication, they ensure that engineering decisions are never made in isolation and that every department feels heard and included.

Fostering Innovation

Strategic Influence: Staying competitive in tech means continuously innovating, and a Principal Engineer’s role is to embed innovation into the team’s DNA. Strategically, they set aside time and resources for experimentation, supporting a culture that’s open to trying new things. They keep a pulse on industry trends, ensuring the team doesn’t stagnate.

Tactical Implementation: On a tactical level, this might look like allocating “innovation time” each sprint where engineers work on exploratory projects or proof-of-concept features. The Principal Engineer may lead an R&D “lab” day or a “tech radar” session where engineers present new tools or patterns they’ve tried. They’re also the gatekeeper, evaluating which trends are worth adopting based on the team’s needs and maintaining a balance between innovation and stability.

Setting (and Enforcing) Best Practices

Strategic Influence: Best practices are the backbone of a high-performing team. Strategically, Principal Engineers set standards that improve quality, maintainability, and security across the board. They know that these standards aren’t just rules—they’re foundations for long-term success.

Tactical Implementation: Practically, this involves creating a living document of coding standards, facilitating code reviews, and implementing tools that enforce these practices automatically. They might use linters, CI/CD pipelines, and automated testing suites to uphold standards. For new practices, they conduct training sessions to bring the team up to speed, ensuring adoption and maintaining consistency across the codebase.

Mitigating Risk Proactively

Strategic Influence: Risk management is a proactive process for a Principal Engineer. They take a wide-angle view of the project, identifying where risks might arise and addressing them long before they become real problems. This means balancing innovation with stability, assessing the cost of technical debt, and evaluating system dependencies.

Tactical Implementation: Tactically, they create a risk matrix that maps potential issues along with mitigation strategies. For example, they might implement dependency checks, introduce chaos engineering sessions to stress-test the system, or establish backups and failover procedures. By embedding monitoring and alerting systems, they ensure that if an issue arises, the team has the tools to respond instantly.

Scalable Systems Built for Growth

Strategic Influence: At the heart of any growing tech project is the need for scalability. A Principal Engineer’s role here is to design systems with growth in mind, anticipating performance needs and making sure the system can evolve without major overhauls.

Tactical Implementation: Tactically, they might start with capacity planning, setting up metrics to monitor load and performance. From there, they consider scalable architecture choices—like containerization or distributed databases—and implement horizontal scaling where appropriate. They also document and plan for scaling triggers so that when demand spikes, the team knows exactly what to do. This ensures the company can confidently expand without hitting a wall on the tech side.


In each of these areas, the Principal Engineer’s influence is both strategic and tactical, providing the vision and the know-how to make things happen. They’re here to guide, solve, and build for the future—ensuring that every choice aligns with the broader mission while also keeping the wheels turning smoothly day-to-day.

That’s what makes the role so invaluable: it’s not just about one person’s work but about lifting the entire team to a higher level, one project, one decision, and one best practice at a time. Stay tuned for more insights here on compositecode.blog (subscribe with your email for delivery direct to your inbox!), where I break down what it takes to build—and lead—great tech teams (along with a plethora of other topics and coding bits).

The Purpose of Principal Engineering

In the world of tech hiring, there’s always a struggle to balance experience with cost, technical chops with the ability to lead. When the stakes are high, and you need more than just code but also architectural vision, that’s where the Principal Engineer comes into play.

But what does a Principal Engineer (or “Staff Engineer”, etc) really bring to the table? And why would a CIO or CTO be willing to invest in this role?

Here’s the deal: a Principal Engineer is more than just a senior developer cranking out code. They’re strategic thinkers, problem solvers, and critical linchpins who hold the project’s technical map in their hands. Here’s a breakdown of the unique value they bring, along with what your leadership should expect when hiring for this pivotal role.

In this post I aim to break down and detail some of the deliverables that a principal engineer is on the hook for. But emphasis is on *some* of the deliverables. The role has specifics per company and org that they’re working with.

Technical Vision and Strategy That Scales

In a fast-paced engineering environment, you need a technical roadmap that not only meets today’s needs but anticipates tomorrow’s challenges. A Principal Engineer builds out this technical vision, aligning it with business goals and real-world needs. They’re not just thinking about if something works—they’re focused on how it’ll work at scale and why those architectural choices make sense for the future.

Deliverable: Expect a Principal Engineer to lay down an architecture that scales, not just through lines of code but through the decisions they make about tech stacks, data models, and more. This isn’t a job for someone who just learned Kubernetes last week; it’s for someone who can see around corners and build with flexibility.

Mentorship and the Power of Knowledge Transfer

Developing a great product isn’t just about code quality or cool features; it’s about building an engineering team that’s ready to tackle hard problems. Principal Engineers are the ones who can share battle-tested strategies, mentor juniors, and help mid-level developers level up.

Deliverable: Look for them to create a structured mentorship setup. This might be in the form of regular code reviews, internal tech talks, or one-on-one guidance that keeps the team sharp. By enabling the growth of others, they’re actively pushing the engineering culture forward.

Complexity Mastered: The Art of Solving the Toughest Problems

When the going gets tough, Principal Engineers don’t back down—they dive into the messiest, most complex challenges. They’re the ones who’ll handle that performance bottleneck, refactor legacy spaghetti code, and still have time to fix a production issue before noon.

Deliverable: At the end of the day, these engineers are problem solvers. A Principal Engineer should be able to present a clean, actionable solution to even the most complicated technical issues, especially those that impact performance, reliability, or scalability.

Cross-Functional Influence

Principal Engineers don’t work in a silo. They’re the ones connecting the dots across design, product, operations, and beyond. They understand the needs of each department and can bring technical priorities into focus without losing sight of business goals. This kind of cross-functional leadership is invaluable, especially in a fast-moving organization.

Deliverable: By ensuring tight alignment between engineering and other teams, they streamline communication and help reduce friction in the development process. In other words, they’re helping the company build things right, the first time around.

Fostering Innovation

The tech industry moves fast, and keeping up isn’t just about attending a few meetups or browsing GitHub. A Principal Engineer actively drives innovation by researching trends, testing out new approaches, and, when relevant, introducing these ideas to the team.

Deliverable: Expect proofs of concept, demos, and thoughtful recommendations on when and how new technologies could benefit the project. Not every idea will hit production, but the ones that do will have a significant impact.

Setting (and Enforcing) Best Practices

Code quality matters, and a Principal Engineer is there to make sure the team doesn’t let good habits slide. This role is about bringing coding standards, CI/CD best practices, and testing rigor to the table, setting the bar for everyone to follow.

Deliverable: Look for them to define a set of standards, document best practices, and create a codebase that can be handed off without a 100-page manual. This also means instilling habits that make future maintenance easier and ensuring the system is built to last.

Mitigating Risk Proactively

Risk is inevitable in any project, but managing it is an art. Principal Engineers don’t wait until something breaks; they’re thinking ahead to avoid issues from the get-go. They proactively identify tech debt, anticipate scaling challenges, and keep an eye on security gaps.

Deliverable: Your Principal Engineer should have a documented risk assessment with clear strategies for mitigation. It’s not about putting out fires—they’re building fireproof structures to begin with.

Scalable Systems Built for Growth

Finally, one of the most important contributions a Principal Engineer makes is creating systems that can grow with the company. They’re looking at how the product will perform when you have 100 users—and how it’ll perform when you have 10,000.

Deliverable: A Principal Engineer should deliver a system that’s efficient, resilient, and ready for scale. Whether it’s a microservices architecture, a well-optimized database schema, or just great code that won’t need refactoring next month, they’re building for longevity.

Final Thoughts

If you’re a CIO or CTO considering adding a Principal Engineer to your team, expect them to bring strategic leadership, advanced problem-solving, and a level of technical acumen that lifts the entire team. They’re not just here to code; they’re here to enable everyone else to code better.

In short, a Principal Engineer should deliver the roadmap for success, the systems to manage risk, and a culture of technical excellence. When done right, their impact is more than the sum of their code—it’s in the tech culture they help create and the problems they prevent long before they happen.


For those interested in digging deeper into tech leadership and how these roles shape successful engineering teams, stay tuned here on compositecode.blog (look for that subscribe button to get posts direct to your inbox!). Let’s keep building the future, one strategic hire at a time!

A few words on getting into Computer Science in 2024 and on?

The journey into advanced software development can feel like plunging into a tumultuous ocean. At first, there’s the excitement of learning—those ‘aha’ moments when distributed systems suddenly make sense, or when the intricacies of concurrency click into place. But once you pass that initial rush, the reality sets in. It becomes clear that mastering these topics isn’t just about understanding technical nuances; it’s also about navigating a web of complexities that intertwine across systems, tools, and people.

This journey brings its fair share of frustration and existential concern. As you go deeper, you start grappling with problems that feel abstract and distant, yet profoundly impactful: distributed state consistency, data synchronization, avoiding deadlocks. You realize that these issues aren’t just technical puzzles; they represent the invisible backbone of everything you’re building. And it’s overwhelming to think how fragile these systems are, how they’re held together by code you and your team write, and how any tiny oversight can cause cascading failures.

Yet, perhaps the most exhausting part isn’t just the code; it’s the human element. Once you develop the social skills to communicate these technical complexities to people at different levels, you realize the challenge isn’t just the knowledge—it’s helping others grasp it without drowning them in details. It’s like being fluent in a language others only have a basic vocabulary for. You spend time rephrasing, simplifying, and drawing analogies, only to have people nod, agree, and repeat the same mistakes next week. They’re not at fault; these are tough concepts. But it can be isolating, being the one person who sees the problem three steps ahead while everyone else is still figuring out step one.

Over time, this endless cycle of repeating the same conversations, explaining the same pitfalls, and warning of the same issues can wear you down. You start questioning the point of it all. Is this just the nature of the field? Does this endless rehashing ever stop? The turmoil lies in seeing the same problems resurface time and again, and knowing that no matter how well you communicate, you’ll be fighting these fires for a long, long time.

But here’s the silver lining—this continuous effort, this cycle of guiding others, is exactly what makes senior and principal developers irreplaceable. It isn’t just the technical depth that sets you apart; it’s your ability to anticipate issues, to teach, and to influence the system holistically. It’s your resilience in the face of this turmoil that gradually turns you into the go-to person in times of crisis.

And despite the weariness, there’s a way to make this journey enjoyable: gamify it. Approach these challenges like missions. Each conversation is an opportunity to refine your communication skills, each system failure a puzzle to decode, each repetitive cycle a level to beat. You can turn these frustrations into a game of progress and accomplishment. Set goals for every interaction—can you reduce the number of repeated questions? Can you guide others towards making the right decisions without explicitly pointing them out? Over time, this mindset can transform what feels like an endless grind into an engaging journey.

These days, if you’re in it just to *code* and work isolated, take a different path. Those elements are either long gone or going away quickly!

While the path may be full of turmoil and frustration, there’s joy in mastering both the technical landscape and the human element of the job. It’s in the moments when a concept clicks for someone else, when a system you’ve stabilized handles chaos gracefully, or when you look back and see how much your guidance has shaped the team. That’s when you realize: this isn’t just a job—it’s a game of building things that matter, of cultivating trust, and of leaving a lasting impact. And in that, there’s both pride and satisfaction.

But What About AI?

In the relentless march of technological progress, Artificial Intelligence (AI) has emerged as both a cornerstone and a disruptor of the computer science field. While AI unlocks incredible possibilities—revolutionizing industries, driving innovation, and creating efficiencies—it also casts a long shadow, revealing the risks and challenges it brings to the tech landscape. For those considering a foray into computer science, the AI-driven shift may not represent the boundless opportunity it once did, but instead a narrowing corridor where the rewards and opportunities are rapidly diminishing.

The Negative Effects of AI on the Industry

One of the most immediate and visible impacts of AI has been the commoditization of skills. Tasks once reserved for highly skilled developers—such as code generation, algorithm design, and even debugging—are increasingly automated by tools like GitHub Copilot, ChatGPT, and others. The result? A devaluation of entry-level and mid-level developer roles. Where junior developers might once have honed their craft through repetitive problem-solving and iterative learning, AI now short-circuits that process, leaving them fewer opportunities to build the foundational skills needed to grow into senior roles.

At the same time, the industry has seen a shift in demand away from generalist developers and towards those with highly specialized knowledge in AI, data science, and machine learning. These roles are fewer and more competitive, requiring not only expertise but also access to costly education and resources. This evolution threatens to widen the gap between those who have the means to thrive in an AI-driven world and those who do not.

Beyond workforce dynamics, AI introduces a new level of unpredictability to the job market. Companies eager to adopt AI for cost savings are increasingly replacing human roles with machine learning algorithms. Automation in areas like customer support, logistics, and even software testing has already eliminated thousands of jobs, and the trend shows no signs of slowing. For aspiring computer scientists, this means entering a field where job security is no longer guaranteed—even for those willing to specialize.

Perhaps more troubling, AI has amplified ethical dilemmas in the tech industry. Developers are now frequently asked to navigate murky waters: Should they contribute to AI systems that could perpetuate biases, deepen societal inequalities, or invade privacy? For many, these questions create a moral conundrum, where the desire to innovate clashes with the potential for harm. The growing influence of AI companies, which often prioritize profits over ethical considerations, leaves many professionals feeling disillusioned and powerless.

Is This the Right Time?

While the allure of computer science remains strong—after all, technology is deeply embedded in nearly every facet of modern life—it’s worth questioning whether this is the field you want to step into right now. The days of abundant opportunities and clear paths to growth may be fading, replaced by an industry that is increasingly automated, specialized, and uncertain. AI, as transformative as it is, has reshaped the landscape, diminishing rewards for all but a select few.

This isn’t to say there is no hope. For those passionate about AI and willing to dedicate themselves to its mastery, there is still potential to thrive. But for others, it’s worth considering whether the cost—financial, emotional, and ethical—is worth the investment. Perhaps, at this juncture in time, computer science isn’t the boundless frontier it once was. It’s a space transformed, where the challenges have grown more complex, and the opportunities, for many, have diminished.

As always, good luck and choose wisely.

Maximizing Impact: Travel as a Developer Advocate

I almost titled this post “Wasting Company Time & Burning Yourself Out” considering some of the interactions and involvement I’ve seen in the DevRel Community of late. But I’ll get to that drama and angry frustrations later in the post, but immediately let’s get down to brass tacks.

As I dive into the nuances of traveling as a Developer Advocate, it’s crucial to clarify that this post isn’t just about logistics or coping mechanisms, but about the larger strategic picture beyond just the tactical underpinnings of day to day travel, airports, train stations, and the like. Instead, I aim to delve into what underpins the demand for travel as a developer advocate. Travel is far more than just getting from point A to point B to partake in an action. It’s about positioning myself—and by extension, the organizations and efforts I represent—to make meaningful connections, drive impact in decisions, and stay ahead in a rapidly evolving industry.

Strategic Travel: Guiding the Future of Major Projects

When it comes to strategic trips, the stakes are high. These aren’t just any industry conferences or casual meetups; they’re focused events where the future of a project might hang in the balance. Take, for example, a situation where a software fork of a major open-source project is on the horizon. The decision to fork isn’t taken lightly—it’s a move that could redefine the project’s trajectory, influence developer adoption, and ultimately shape the software landscape for years to come. Being on the ground and having built connections with the people involved face to face is irreplaceable. Having just had few meetings or video conf calls doesn’t cut it, one can’t replace the built trust of time spent face to face builds. This is where traveling to where people are, as an advocate, become priceless.

In these scenarios, my travel is centered around influencing and guiding these pivotal moments. I’m there to represent the interests of my company, to ensure that our vision and goals align with where the project is heading. This might involve meeting with the core contributors, understanding their motivations, and providing insights that can help steer the project in a direction that benefits both the community and the enterprise. It’s about being at the table when decisions are made, rather than reacting to them after the fact.

Similarly, when a new, large organization steps in to take over governance of a project, the dynamics can shift dramatically. My role here is to establish relationships early, understand the new leadership’s vision, and offer strategic input that aligns our goals with theirs. This isn’t about forcing our agenda—it’s about finding common ground where both parties can thrive.

Tactical Travel: Building Connections in the Industry

On the tactical side, the focus is more granular but equally important. Every trip to a conference, meetup, or industry event is an opportunity to meet, learn from, and exchange ideas with peers across startups, SMBs, and large enterprises. These interactions are where I gather insights on how different organizations are tackling similar challenges, what tools they’re using, and what their desired outcomes are.

For instance, attending a conference might put me in touch with a key decision-maker at a startup that’s just beginning to scale. They’re facing challenges with their CI/CD pipeline, and they’re considering a move to a new platform that I’ve been advocating for. Through our discussions, I can provide them with the insights they need to make that decision confidently, while also gaining a deeper understanding of the pain points that are driving their choices.

Similarly, meetups offer a more informal setting to connect with the implementers—the engineers and developers who are in the trenches, building out the solutions that will power tomorrow’s technologies. These conversations are invaluable. They allow me to see firsthand how our tools and platforms are being used in real-world scenarios, and they provide an opportunity to gather feedback that can be fed back into our product development cycles.

In every tactical interaction, my goal is to build relationships that extend beyond the immediate conversation. I’m looking to understand the missions of the people I meet—what are they trying to achieve, what challenges are they facing, and how can I help them get there? These connections are the lifeblood of developer advocacy, and they’re what make the travel worth it.

Managing Travel as a Developer Advocate: Balancing the Chaos

With the strategic and tactical intent in mind, the actual process of managing travel becomes a critical component of the job. Travel as a Developer Advocate isn’t just about attending events; it’s about maximizing the impact of every trip while maintaining personal and professional balance.

The Art of Pre-Travel Prep

Preparation is where it all starts. Before I even think about boarding that plane, train, boat, or whatever my mode will be, I make sure my travel plans are bulletproof. This means having a clear itinerary, knowing the lay of the land in the cities I’m visiting, and ensuring I’ve got all the necessary tools and backups for work.

Itinerary: A well-planned itinerary is crucial. It’s not just about knowing which sessions I’m speaking at or what meetings I have lined up. I go deeper—knowing where the local coffee shops are (because who can function without a good coffee?), having a couple of backup restaurants that cater to my dietary preferences, and being aware of the quickest routes to my hotel or the event venue. Google Maps is my best friend here, and I often create custom maps to keep all this info in one place.

Tools & Backups: As a Developer Advocate, my gear is my lifeline. This includes the obvious—laptop, charger, phone—but also the not-so-obvious. I always carry a portable battery pack, a universal adapter, and a mini Ethernet cable (you never know when Wi-Fi might betray you). Cloud backups are a must; I make sure all my important files and presentations are synced to a secure cloud service before I even leave the house. It’s also not uncommon for me to bring or ship ahead of time key assets for redundancy; a laptop, thumb drive with collateral on it, or other items. Because even a cloud backup isn’t insured against a conference just having bad wifi or wifi that won’t enable you to download something last minute!

Once on the trip, the hustle begins. Airport lounges, train stations, hotel rooms, coworking spaces, and event centers become my makeshift offices. Here’s how I keep it all running smoothly.

Time Zones & Sleep: Jet lag is real, maybe I’ll speak specifically about how I deal with it one day. But for now let’s focus on the fact it can derail your productivity fast. I’d suggest trying to adapt to the new time zone as quickly as possible by adjusting your watch as you board the plane, start living in that time zone the moment you’re in route.

International: If you’re traveling internationally it’s good to check what you’ll have or not have access to. For example if you’re going to China, forget the Internet. If you’re going to Russia, we need to have a talk, write me on the contact form about the worst ideas you could have. If you’re traveling to most of Asia (India, Japan, etc) you can have vastly different quality of service and various other ramifications to deal with. In Europe you’ll likely have great service but there will be nuances to deal with. For example, the age old Netflix issue, you’ll have a whole new slew set of shows depending on what is licensed where. Be prepared for this, look up the details of where you’re going, and work to mitigate the issues.

Staying Connected: Reliable internet is a necessity. I make sure I have an international data plan or a portable Wi-Fi device that works in the countries I’m visiting. The last thing you want is to be stuck in a situation where you can’t access the internet, especially if you’re about to go live on a webcast or need to push that critical code update.

Health on the Go: Travel WILL take a toll on your body that over time isn’t particularly positive. You absolutely have to actively work – A LOT – to mitigate the harmful effects of wearing yourself out traveling. I’ve made it a point to maintain a healthy routine while traveling, staying active, and also being sure to hydrate appropriately (especially with air travel). I carry a water bottle to stay hydrated (yeah yeah yeah very “American”), pack some healthy snacks to avoid the temptation of junk food, and I often get a work out by bringing my Brompton, a full size bike, or even rent one for use on trips. Basically, I stay as close to active while traveling that is similar to how I live. If you don’t, all the negatives will come after you: extra tiredness, weight gain, hydration issues, extra stress, you name it! You gotta do things that will work for you, so obviously it’s a learned experience once you’re out there, my advice is to keep this top of mind. Not a little toward the top, but literally the TOP of mind, first thing you start dealing with anywhere you go.

What Makes a Good Trip?

A successful trip is one where both strategic and tactical goals are met without disrupting the core mission of advocacy. The ideal trip balances advancing the broader objectives—such as influencing a major project’s direction or building new industry relationships—with the day-to-day work of staying deeply connected to the technology, product, or solution at the heart of the advocacy role.

A good trip ensures that even while attending conferences, meeting with key decision-makers, and exploring the latest trends, there’s still time to maintain the rhythm of work that keeps me on top of the technology I’m advocating for. It’s about keeping up with the latest developments, prototypes, and product updates, ensuring that my knowledge remains current and my advocacy effective.

However, too much travel can be counterproductive. It’s easy to lose touch with the core underpinnings of the technology if you’re constantly on the road. The balance is delicate; typically, 1-3 trips per quarter is ideal. This cadence allows enough time for learning and growing with the technology while still making meaningful connections through strategic and tactical travel. Anything beyond that increases the risk of disconnecting from the very core of what makes advocacy successful: an intimate, ongoing engagement with the technology and community you’re representing.

The Wrap Up

Travel as a Developer Advocate is a multifaceted challenge that demands a balance of strategic foresight and tactical execution. Whether guiding the future of a major project or building connections at industry events, each trip is an opportunity to make a meaningful impact. By preparing thoroughly, staying adaptable on the road, and reflecting on the journey, I can ensure that every trip contributes to my goals as a Developer Advocate.

But beyond the immediate goals of each trip, it’s crucial to maintain a consistent connection to the technology, product, or service being advocated for. Too much travel can create a disconnect from the very mission of advocacy. The key is to strike a balance—traveling enough to build strategic relationships and gather insights, but not so much that it disrupts the deeper work of staying connected to the technology and community.

In the coming posts, from my own experiences and from my interest in developer advocacy, I’ll explore strategies for maintaining this balance, ensuring that travel enhances rather than hinders the mission. I’ll delve into how to manage efforts effectively when balancing trips to conferences, meetings with customers, and other events with the day-to-day work that keeps a Developer Advocate grounded and effective. For good measure, I’ll throw in some bike tips here and there! Stay tuned!

The Missing Pieces: What Online Tutorials and Docs Always Seem to Forget

Yo, fellow coders and tech enthusiasts! Adron here, and today we’re diving into a topic that’s been grinding my gears for ages – the stuff that’s always missing from online tutorials and docs. Buckle up, ’cause we’re about to get grumpy!

0. The Invisible Prerequisites

Before we even get to the main course, let’s talk about the appetizer that so many tutorials forget to serve – the damn prerequisites! I can’t tell you how many times I’ve started a tutorial only to find out halfway through that I needed some obscure tool or specific version of something that wasn’t mentioned upfront.

Here’s the deal, tutorial writers: lay out ALL the prerequisites clearly at the beginning. And I mean ALL of them. Don’t assume I have jq installed for your GraphQL tutorial. Don’t assume I’m running the latest version of Python (and for the love of code, specify WHICH Python – 2.x or 3.x?).

And here’s a novel idea: how about actually telling me where to find and install these prerequisites? Give me links, give me version numbers, give me command line instructions. Assume I’m starting from scratch on a fresh machine. Because guess what? Sometimes I am!

Even though this isn’t a tutorial, but just because I mentioned them here, check out jq here and Python here.

1. The “Why” Behind the Code

Look, I get it. You’re excited to show off that sweet new framework or library. But for the love of all that is holy in the tech world, tell me WHY I should care! Too many tutorials jump straight into the how without explaining the why. Give me context, people! I get that jq is cool (yeah, that thing again!) but why do I want to mess with JSON from the command line, the ole’ terminal, or the bash or zsh, explain to me why it matters. I know it might seem to you to make sense, but often there is a lot of context missing up front, fill in the context.

2. Real-world Use Cases

Sure, your “Hello World” example is cute. But when am I ever gonna need to print that in production? Give me some meaty, real-world scenarios. Show me how your tool solves actual problems developers face in the trenches. This is of course hard, it is of course time consuming, and it can be painfully difficult to work up and example in a timely manner and actually finish a blog post on a particular piece of tech. It does take a lot of work, but if we want an article to be effective, readable, and usable over time it’s got to have some meat to it.

3. Error Handling and Debugging

Everything works perfectly in your tutorial? That’s adorable. In the real world, stuff breaks. A lot. Show me how to handle common errors, how to debug when things go sideways, and how to not lose my mind in the process.

One of the best ways I’ve found to add error handling and debugging is to work through the example I’m going to present from a fresh machine. It forces me to find the prerequisites but also run into all sorts of errors and what ifs. Presenting only the happy path just doesn’t always help, throw in some curve balls and at least talk through in a post what error handling or debugging might look like.

4. Performance Considerations

Yeah, your code runs. But will it scale? Will it choke when hit with real traffic? Don’t just show me how to implement something – show me how to implement it efficiently.

This is something, in my not humble opinion, every single database topic should start with and end with a performance conversation. The number of poorly designed databases I’ve fumbled upon out in the wild, once I’ve reverse engineered them and discovered the history I’ve found a single thing in common with poorly performing databases. Simply that, performance and end outcome wasn’t taken into account. This should be the first step of creating any data storage mechanism, but also any operations on data the code, database, cache, or other layer.

5. Security Implications

In this day and age, ignoring security is like leaving your front door wide open with a “Rob Me” sign. Walk me through the security considerations. What are the potential vulnerabilities? How do I protect against them?

But wait, maybe that analogy isn’t right. It’s the internet after all, maybe it’s more like installing a front porch on your house and taking off the front door and the entire front wall. Exposing your living room to the world and just offering to have the community stroll through it. That’s more like it, so yeah, security needs to be a high priority topic in most circumstances. Be thorough, be accurate, include a thought or three about how one locks down the topical tech bits you’re rambling on about.

6. Integration with Existing Systems

News flash: most of us aren’t working on greenfield projects. Show me how your shiny new tool plays nice with legacy systems. How do I integrate it into my existing stack without bringing down the whole house of cards? This could, like several of these suggestions, be merely a conversation paragraph or two about thoughts on integration with existing systems, to the ultimate by having examples of integrations.

7. Testing Strategies

Unit tests are great, but they’re just the tip of the iceberg. Give me the full testing spectrum – integration tests, end-to-end tests, performance tests. Show me how to sleep soundly knowing my code won’t implode in production.

At this point in time, this seems like something that shouldn’t even be mentioned. Kind of like showing an example of the actual thing you’re talking about in the first place. If you’re going to show how to implement X with Y library or something, we all need to see Y library under test with X implemented. A new drag and drop feature, “cool!”, but how the hell do you test that?

8. The Devil in the Details

Alright, let’s talk about something that drives me up the wall – the missing small steps. You know what I’m talking about. Those tiny, seemingly insignificant details that tutorial writers assume everyone knows. Newsflash: we don’t!

I can’t count the number of times I’ve been following a tutorial, feeling good about myself, when suddenly I hit a wall because the author skipped over some “obvious” step. Maybe it’s how to set up a virtual environment in Python. Maybe it’s how to properly configure your PATH. Or maybe it’s just how to navigate to the right directory in the terminal.

These might seem trivial to you, oh wise tutorial writer, but to a newbie or someone coming from a different tech stack, these small steps can be the difference between smooth sailing and a frustrating afternoon of Googling and hair-pulling. At least, if it seems somewhat unreasonable to add specific details, at least mention and link to where one might find the details. For example, as mentioned above, where is a tutorial getting a virtual environment setup for Python, like this one, or the step even before that one.

So here’s my plea: Don’t assume anything. Walk us through every. Single. Step. Even if it seems painfully obvious to you. Because what’s obvious to you might be a revelation to someone else. And isn’t that the whole point of a tutorial?

Look, I get it. Covering all this stuff is hard. It takes time, effort, and a deep understanding of your tool and its ecosystem. But that’s exactly what separates the mediocre docs from the stellar ones.

So, to all you documentation writers and tutorial creators out there: step up your game. Your users will thank you, and the coding world will be a better place for it.

Now, if you’ll excuse me, I’ve got some legacy code to wrangle and a cup of coffee with my name on it. Keep coding, keep learning, and for Pete’s sake, keep documenting – every single step of the way! 🤘🏻