Ask Hartley Anything

#8 Documentation and the Council of Elders

From an environment perspective, having solid documentation supports stability and productivity. So let’s tackle a tough question: What makes good documentation? First off, there's no such thing as perfect documentation—just like there's no perfect code. The key is producing and maintaining it consistently. Documentation requires a different thought process than coding; it's more creative and explanatory. AI Summary provided by Audiopen.ai [https://audiopen.ai?aff=XK1wX], the only AI tool I pay for (affiliate link [https://audiopen.ai?aff=XK1wX]) This brings me to the Diataxis framework. It categorizes documentation into four types: how-to guides (practical steps for tasks), tutorials (learning-based steps), references (quick look-ups for APIs), and explanations (theoretical understanding). This framework helps determine what kind of documentation is needed based on its purpose. Diataxis helps organize information but doesn’t dictate where it should live—that's up to each organization. It’s like agile processes; each team adapts it to their needs. So does Diataxis provide insight into organizing documentation? Not directly; it focuses more on categorizing content rather than structuring it within an organization. Each team must figure out their own system based on their dynamics. You mentioned implementing a documentation council at work. How does that function? Our council consists of representatives from each feature team who audit existing documentation and handle requests for new docs or updates. We meet periodically to review what we have and what’s needed, creating tickets for updates or new documents as necessary. When someone requests documentation, how does that process look? We kick off audits once every quarter or six months, review existing docs for relevance and accuracy, then create tickets for necessary updates or new documents based on feedback from teams. In fast-paced environments like Dynamit, how would you implement such practices? It’s challenging but crucial to allocate time for documentation even in fast-paced settings. Managers need to push for this time allocation while developers should embrace professionalism by thinking about future maintainers of their code. How do you balance code comments versus external documentation? Consider who will consume your code: API layers need explicit docs while feature teams might need detailed comments within the code itself. Capture feedback during onboarding to continuously improve your process. If you don’t have a council yet, where do you start? Start small by identifying passionate individuals who care about clarity in their work. Give them responsibility over documentation as part of their career growth trajectory—it’s low stakes but high impact. Thanks for sharing these insights, Michael! It's not something your end user will see, but it provides juniors and mids with tangible tasks to demonstrate leadership abilities. For others, it's an opportunity to improve things, which is a common goal. Junior engineers, curious about the code and still learning, might notice a lack of documentation. They could spend a day or two diving in, understand it, and present their findings to the team. I've noticed a trend in organizations heavy on Slack or Teams using video for documentation. Tools like Loom allow for recording changes and explanations. Historically, we preferred written documentation as a contract with everyone. However, long documents can be overwhelming. A five-page document feels like a wall of text; even I struggle with comprehension without multiple reads. TLDRs help in understanding the core quickly. Videos as documentation are great but come with challenges. Tech talks at our organization contain valuable information, but making them accessible and searchable is tough. Tools like Microsoft Stream offer solutions by uploading videos, generating transcripts using AI, allowing comments, and deep linking to specific sections. This makes videos searchable and collaborative. AI tools are evolving to assist in documentation. Tools that grok APIs and generate documentation or transcribers like Otter that take meeting notes are helpful. AI tools can retrieve information efficiently but should be used cautiously for generating content. The industry's direction seems to favor tools like Microsoft Stream becoming more available. Properly cultivated video documentation can be as essential as written docs for quick reference and communication. As for AI tools in documentation, they can create knowledge bases isolated from the public domain. Integrations with platforms like Confluence make information retrieval easier. However, I caution against relying on AI for generating content; it's better suited for retrieval. While AI can cover up issues instead of fixing them, we must scrutinize its output rigorously. Use AI as a tool without letting it replace human judgment. Documentation is an investment for the future and those who will replace you eventually. For new engineers, taking extensive notes while learning can form useful documentation later. It's about professionalism and continuous improvement—start small, iterate, and build a documentation culture. In summary: dedicate time to documentation, use frameworks like Diataxis for guidance, leverage AI as a tool (not a replacement), and focus on continuous improvement. For further questions on documentation, I'm available on LinkedIn. This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit hartleyshandbook.com [https://hartleyshandbook.com?utm_medium=podcast&utm_campaign=CTA_1]

#7 Balancing Code & Leadership + The Power of Sponsorship & Recognition

Welcome back to Ask Hartley Anything, the podcast where I tackle your questions and share lessons from my journey as an engineering leader. This is episode seven, and today we’re diving into two topics that are close to my heart. First, how do you manage your time and yourself when you're a manager expected to code? Second, sponsorship and recognition in leadership—how do you sponsor and recognize your team members effectively? Summary provided by AudioPen Prime [https://audiopen.ai/?aff=XK1wX], the only AI tool I pay for. Goes from audio thoughts to transcribed summaries in whatever style you’re looking for. Love using this for long drives or walks. Before we jump in, remember you can always go to askhartley.com [https://askhartley.com] to submit your questions anonymously or with your name. I love working through these questions because management is something you learn by doing, often impacting those around you. So thinking through these scenarios helps prepare for when they arise. Let's start with balancing coding and leadership as a manager. Imagine you're a front-end lead managing four people while still expected to contribute to projects. You might think a 50-50 split between management and coding will work, but it's not that simple. The context switching between coding and managing is vastly different. Coding problems are direct—either it works or it doesn’t. People problems are nuanced; solutions may take months to reveal their effectiveness. So don't expect a strict 50-50 split. Priorities shift weekly; some weeks require more focus on individuals, others on code. The urgency also differs—a critical bug needs immediate attention, while a personal issue with a team member requires empathy and understanding. Next, consider perception and expectations. Your team expects you to stay technical while leadership wants you focused on strategy. As an individual contributor, your job was to write and deliver code. As a manager, you're expected to see further ahead, strategizing across teams and projects. Balancing these roles is tough, especially if it’s your first time managing. Strategy and people problems will be new territory, taking longer at first—and that’s okay. Here are some strategies that worked for me: * Time Blocking: It didn’t work well for me because interruptions are inevitable in management roles. If you try this, be very clear with everyone about your availability during these blocks. * Prioritize Value: Focus on smaller tasks that add value without becoming bottlenecks for your team. Let them handle complex issues requiring deep thought. * Delegate and Coach: Shift from execution to coaching. Delegate critical tasks but stay involved through PR reviews and architectural decisions without being the sole decision-maker. * Set Boundaries: Communicate clearly about when you'll be heads-down coding versus available for team issues. Remember, as a manager who codes, your role is about multiplying the team’s effectiveness—not just executing tasks yourself. Now onto our second topic: Sponsorship and recognition in leadership... Strong sponsorship increases retention, morale, trust, fairness, and encourages diverse leadership growth. Your success as a leader isn’t just about what you accomplish—it’s about who you elevate along the way. On sponsorship and recognition, it's about elevating others and strengthening both individuals and the organization. Put them in the spotlight, amplify their voices, and ensure they're heard even if they’re quiet. Moving on to sponsorship and recognition in leadership: Recognition drives engagement, retention, and career growth because it shows what behaviors are rewarded. Sponsorship helps underrepresented employees advance by putting them in visible positions. There’s a difference between sponsorship and mentorship—mentorship offers advice; sponsorship actively advocates for someone's career growth by giving them opportunities for visibility. Here are some practical ways to sponsor as a leader: * Public Credit: Acknowledge team members' work in meetings or updates without taking credit yourself. * Create Visibility Opportunities: Pull team members into decision-making meetings or let them present topics they’re experts in. * Push for Promotions/Raises: Document their impact consistently so it’s easy to advocate for them during promotion cycles. * Assign Stretch Projects: Give high-potential employees critical projects to build their credibility. * Celebrate Day-to-Day Wins: Regularly highlight both big achievements and small improvements in team communications. So, how do you balance leadership and coding? Who has sponsored you, or whom have you sponsored in your career? Share your thoughts at askhartley.com or message me on LinkedIn. That wraps it up for today. Next week, we'll have Michael Yodiv, a colleague of mine, discussing documentation. If you have questions about documentation in current, previous, or future organizations, drop me a note at AskHarley.com. We'll answer them live in a rapid-fire session—it’s going to be fun! That's all for Episode 8 next week. Thanks for listening. Have a great week! This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit hartleyshandbook.com [https://hartleyshandbook.com?utm_medium=podcast&utm_campaign=CTA_1]

The Balance Between Ambition and Self-Compassion

Welcome back to Ask Hartley Anything, episode six. I'm your host, John Hartley, and every week I take your questions and share insights from my journey as an engineering leader. Today, we're diving into a topic that's close to my heart: giving yourself grace. This means allowing yourself room to breathe, not being overly critical or pushing yourself too hard. It's something I've struggled with for a long time, and while I'm still working on it, I hope to shed some light on the subject. Maybe you're grappling with this too, and we can work through it together. Summary provided by AudioPen Prime [https://audiopen.ai?aff=XK1wX], the only AI tool I pay for. Goes from audio thoughts to transcribed summaries in whatever style you’re looking for. Love using this for long drives or walks. Today, we'll explore why we push ourselves so hard, how it affects us, practical strategies for balancing ambition with self-compassion, and the long-term benefits of permitting yourself to rest and recover. If you've ever felt like you're not doing enough, this episode is for you. Even getting this episode out was a struggle for me—I debated whether to push myself or take a break. But I committed to releasing episodes weekly this year, so here we are. Burnout is an issue we face daily, so let's dive in. Why do we feel this way? Why do we push ourselves too hard? Much of what I'll share comes from my own experience. For instance, I ran a hot sauce company on the side while managing my day job and personal life. It was exhausting and led to burnout. The culture of overwork is finally starting to fade away, but hustle culture still lingers. Social media often glorifies constant productivity—early mornings, cold plunges, 10-mile runs before breakfast. This lifestyle can make us feel inadequate if we're not doing the same. This year, I've switched to audiobooks instead of stressing about reading physical books quickly enough. Oddly enough, manga like Berserk keeps my attention better than traditional books. Why do we push ourselves? Fear of failure and imposter syndrome play a big role. Early in my career at a digital agency, I pushed myself so hard that I got stress-induced shingles twice. The fear of being seen as a failure or unreliable drove me to overwork. This self-imposed pressure is something I've reflected on for years. We often equate more effort with more success, but sometimes stepping back is the most productive thing we can do. Think about where you're being hard on yourself and why. Are you pushing too far? In engineering leadership, I promote work-life balance heavily. If someone hasn't taken time off in a while, I encourage them to do so—not because they're doing a bad job but because they need to take care of themselves. We've created a culture where we're always on, especially in tech. Some colleagues don't even have Slack on their phones—setting boundaries is crucial. Let's talk strategies for giving yourself grace: 1. Reframe Your Mindset: What does success mean to you? For me, it used to mean climbing the corporate ladder as fast as possible. Titles aren't everything; they don't necessarily equate to impact or satisfaction. 2. Perfectionism: Are you trying to be perfect or good enough? Be okay with 80%. Perfection isn't realistic; aim for progress instead. 3. Set Boundaries: Define clear working hours and stick to them. Use tools like Google Calendar and Slack notifications wisely. 4. Practice Self-Compassion: Talk to yourself like a friend would—replace criticism with kindness and encouragement. 5. Acknowledge Wins: Keep track of your accomplishments, even small victories—they build momentum and positivity. Lean on your network when you're struggling—having a hype person can make all the difference. And if you're still finding it tough, seeking professional help is okay too. Understanding your boundaries and relationships is critical as you navigate your career. Reflecting on your progress regularly helps maintain balance and growth. So think about what makes you happy and gives you joy in life. Give yourself some grace and set boundaries that work for you. Pushing yourself too hard generally leads to burnout rather than success. Reframe what success means for you—prioritize what matters most. What's one thing you'll give yourself grace with this week? I'd love to hear your thoughts—reach out at askharley.com or connect with me on LinkedIn. Thanks for listening! We'll be back next week with episode seven—possibly discussing documentation in engineering organizations with a special guest! Until next time, take care of yourselves! This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit hartleyshandbook.com [https://hartleyshandbook.com?utm_medium=podcast&utm_campaign=CTA_1]

The Art of Goal Setting: For You, Your Team, and Your Company

Welcome back to Ask Hartley Anything, the podcast where I take your questions and share insights from my experience as an engineering leader. With 15 years in the software industry, eight of which have been in engineering leadership, I’ve learned a thing or two about goal setting. Summary from Audiopen.ai Prime [https://audiopen.ai/?aff=XK1wX] (affiliate link for the only AI tool I pay for) I teased this topic a couple of weeks ago, but today, we’re breaking it down. When setting goals, think in three ways: personal growth, team growth, and company growth. Even as an individual contributor, this approach ensures you're always growing and helping your team and company grow too. Before we dive in, remember you can always ask questions at askhartly.com or find me on LinkedIn. I also have a weekly newsletter every Monday with helpful links on AI, goal setting, leadership, and more. If you’d like to submit a link or learn more, feel free to reach out. Alright, let’s get into goal setting. Especially at the beginning of the year, it's critical to get this right. The main framework I use is SMART goals—Specific, Measurable, Achievable, Relevant, and Time-bound. Specific means your goal is clear. Instead of saying I want to get better at this, say I want to improve my one-on-one skills. Measurable means figuring out how to quantify your progress. Achievable means the goal is realistic within the time frame you set. Relevant relates to your role and career growth. Lastly, Time-bound means setting a clear deadline—whether it’s a week, a quarter, or a year. So how do you set goals for yourself? Focus on how you want to grow as an individual. If you're an engineer, it might be mastering a new technology or taking on more leadership responsibilities. Avoid checkbox goals like complete a React course. Instead, aim for something actionable like complete the course and deliver a presentation on what I've learned. Personal goals are helpful because they allow you to track your growth over time. Setting goals gives you clarity on what’s important and helps identify obstacles that might be hindering your progress—be it too many meetings or too much busy work. Now let’s talk about team goals. Even as an individual contributor, you can set goals that impact your team. For instance, improving a process or reducing meeting times can significantly affect team dynamics and outcomes. From a software perspective, think about team goals as outcome-oriented. For example, logging more bugs should lead to reduced bug resolution time or fewer overall bugs. Aligning team goals with company objectives ensures everyone is moving in the same direction. Speaking of company goals, these often trickle down from broader objectives like OKRs (Objectives and Key Results) or KPIs (Key Performance Indicators). These should be specific enough to guide teams but flexible enough to adapt as needed. Setting company-wide goals requires vision and alignment across all teams. For instance, improving customer satisfaction by 10 points in CSAT could involve various teams working on different aspects like UX improvements or technical debt reduction. Regular updates and transparency are key in tracking progress towards these goals. Using simple metrics like stoplights—red for off track, yellow for at risk, green for good—helps everyone understand where things stand and what needs attention. In summary, start with yourself by setting clear personal goals using the SMART framework. Expand to collaborative team goals that align with your organization’s vision. And finally, contribute to company-wide goals that act as your North Star. What goals are you setting for yourself in 2025? What about for your team or company? Let me know at askhartly.com or find me on LinkedIn. This podcast airs every Wednesday morning on Spotify, iTunes, at hartleyshandbook.com—wherever you find your podcasts. If you have any other goal-setting frameworks or systems that work for you, I'd love to hear about them. Thanks for listening! Until next time, take care and keep setting those meaningful goals! This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit hartleyshandbook.com [https://hartleyshandbook.com?utm_medium=podcast&utm_campaign=CTA_1]

Mastering Decision-Making: Empowering Teams and Mental Models

Summary from Audiopen.ai Prime [https://audiopen.ai?aff=XK1wX] (affiliate link for the only AI tool I pay for) Hey everyone, welcome back to Ask Hartley Anything, Episode 4. This is the podcast where I take your questions and share insights from my journey as an engineering leader. Today, we’re diving into mastering decision-making—empowering both your teams and yourself to make faster decisions, along with some mental models to help you do that. We’ll provide frameworks and systems so it’s not as overwhelming. Before we get into the first question, remember you can go to askhartley.com [https://askhartley.com] to submit your questions, anonymously or otherwise. So far, we’ve been able to cover all four episodes with questions from you. I initially started this unsure if folks would actually send anything in, so I'm thrilled you're doing that and appreciate every question. Today’s topic is helping teams make decisions confidently and using mental models for better, faster decisions. Our question comes from “third place,” possibly referencing a Fantasy football league—I'm not entirely sure. Third place asks: Hey John, in episode two you briefly mentioned over-democratizing decision making. Could you elaborate more on this topic and how to realign your team so people feel comfortable making decisions? Does a tech lead need to step up as somewhat of a dictator to ensure timely decisions? Is this a superpower bestowed by management or leadership? Great question! If you haven’t listened to Episode Two, feel free to go back after this one. Over-democratizing decision-making can be a problem in organizations. It’s when every decision is put out for a vote or discussion, dragging on endlessly. While it’s good to get differing opinions, it shouldn’t hinder timely decision-making. I’ve seen this happen with RFCs (Requests for Comments) in engineering organizations. You put up a proposal for something like a big architectural change, and it either gets stuck in endless comments or no one responds at all. One way to resolve this is by giving tight timelines: say you have a week for comments, then you’ll address them and make a decision. A key decision-maker can help break the cycle of indecision—whether that’s your VP of Engineering or a group of directors. Sometimes a simple thumbs-up/thumbs-down vote can work too. Fear of making the wrong decision often paralyzes teams. It’s crucial to foster a culture where failure is acceptable and reversible decisions are encouraged. For instance, in code, you can revert changes or use feature flags to test new implementations. I prefer POCs (Proofs of Concept) over RFCs because they allow you to test ideas quickly without getting bogged down in endless debate. A POC shows tangible progress and helps move things forward faster. Now, who makes the final decision? It depends on the size of the decision. Smaller decisions can be made by tech leads or senior engineers within their teams. Larger system changes might need input from staff engineers or even higher up the chain like VPs or CTOs. For major strategic shifts like re-platforming, involving top leadership makes sense since it aligns with the company's overall strategy. To avoid micromanagement and promote autonomy, give teams frameworks for decision-making. Document how decisions should be made within your organization so everyone knows the process. Curious how decisions are made at your company? Writing it out can reveal how democratized your process really is. But don’t let decisions linger; set deadlines for making them. Switching gears slightly—if you want resources on better decision-making, Daniel Kahneman's Thinking Fast and Slow is excellent. Remember that all decisions are made with partial information; you'll never have every piece of data. Let’s talk about some mental models: 1. **Eisenhower Matrix**: Prioritize tasks based on urgency and importance. 2. **Opportunity Cost**: Consider what you're giving up by choosing one option over another. 3. **OODA Loop**: Observe, Orient, Decide, Act—a continuous improvement cycle. 4. **Inversion**: Instead of asking how you can succeed, ask how you could fail and mitigate those risks upfront. These models help create repeatable frameworks for making faster decisions with confidence. So we've covered decision-making and some mental models today. If you have more questions, visit askhartly.com or find me on LinkedIn. Thanks for listening! Tune in next week for Episode 5. This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit hartleyshandbook.com [https://hartleyshandbook.com?utm_medium=podcast&utm_campaign=CTA_1]