Writing Code Documentation

Why Articulation & Stakeholder Skills Matter More Than Ever for Data Engineers As AI gets smarter, writing code isn’t the differentiator anymore. Explaining your work, influencing decisions, and building trust—that’s what sets great engineers apart. That’s why I follow the 50:50 rule: 💡 50% doing the work. 50% talking about the work. My win this month I focused intentionally on building relationships with stakeholders. Alignment takes time, but trust starts small—one clear explanation, one thoughtful question, one consistent follow-through. The result? Stakeholders now see data engineers as partners, not just executors. That shift in perception is the real win. Why this matters for every technical professional You can design the perfect pipeline or architecture… but without articulation, the value gets lost. Strong communication gives you: • Faster decisions • Fewer misunderstandings • Bigger ownership • More strategic influence How to build this skill (practical + fast): 1. Explain your work in business-first language 2. Summarize your updates clearly and proactively 3. Break complexity into simple layers 4. Invest in micro-trust moments with stakeholders AI can generate code. AI cannot build trust. Your technical skills build solutions. Your articulation turns them into impact.

As a software engineer, I've learned the hard way that details ≠ clarity. When communicating with executives, every extra word dilutes your message. Despite coaching and training, I still catch myself diving too deep and losing my audience – but recognizing this tendency and having the right tools has been helpful. Three insights that changed how I communicate complex technical concepts: - Lead with impact: Start with what matters most. For that exciting GenAI proposal? "This will transform how users experience our product" comes before any technical architecture. - Context before complexity: Show why it matters before how it works. Your audience needs to care before they'll dig into details. - Layer your message: Start high-level, then provide paths to technical depth. Not everyone needs your debugging journey. The reality? In today's world, you have seconds to make your point. The clearer you communicate, the more influence you'll have. That’s not to say we shouldn’t have the details in our head. It’s just part of getting stuff done.

When I started my career in tech, a senior once told me something that has always stayed with me: “In IT, If it isn’t documented , it doesn’t exist” Back then, it sounded dramatic. Today — after multiple projects, rewrites, discussions, and shifting priorities — I know exactly what he meant. Conversations get forgotten. Feature discussions evolve. And verbal agreements… disappear faster than you expect 😬 It’s not about mistrusting people. It’s about creating clarity, continuity, and accountability in a world where teams change, priorities shift, and memory is unreliable. Over the years, here’s what experience has taught me: 👉🏻Document every decision — even a short summary message after a call can protect you months later. 👉🏻Record the “why,” not just the “what.” Context is gold when you revisit old features or debug old logic. 👉🏻Don’t rely on verbal approvals — put it in writing to avoid the classic “I never said that” moment. 👉🏻Keep your notes organized or have proper documentation — future you will thank you when a discussion resurfaces out of nowhere. The funny thing is: documentation doesn’t feel like a “tech skill,” but it’s one of the most underrated trait of a strong engineer. Because in IT, your memory might fail — but your documentation won’t. #softwareengineering #productivity #communication #careeradvice #freshers #sde #jobs

The underrated skill that gets junior and mid level developers noticed. It's not algorithms. It's not framework knowledge. It's not even clean code. It's communication adaptation. As a self-taught developer who advanced quickly, I noticed most technical people make a critical mistake: They communicate with everyone the same way. They explain concepts to product managers the same way they talk to other developers. They discuss timelines with executives the same way they discuss them with their tech lead. When I started reading the room and adapting my language: - With business stakeholders: I focused on impact, not implementation - With designers: I talked about user experience, not code structure - With senior devs: I discussed technical trade-offs - With product managers: I translated technical limitations into product decisions My ability to switch communication styles made me the go-to person for cross-team projects. This skill from my previous careers became my secret weapon in tech. People started saying: "Let's have [your name] join the meeting - they can translate this for everyone." That visibility fast-tracked my career more than any technical achievement. What's one conversation you have tomorrow that could benefit from adapting your communication style?

The problem with keeping code and documentation separate. It tends to diverge over time. So most software documentation should be replaced with highly readable code and tests. However, no matter how readable the code is, it doesn’t give us the context behind why the code exists in the form that it does. To address this software engineering teams should be keeping Architecture Decision Records (ADRs). These are lightweight documents that capture important architectural decisions along with the when, how and why of the decision. ADRs are particularly useful for agile projects where not all the decisions will be made at once and long lifetime projects where a new person joining the team, or someone who hasn’t worked on part of the project recently, will need to understand the rationale and consequences of a decision that has been made in the past. An ADR should record: 1. When the decision was made. 2. The status of the ADR (proposed, accepted, rejected, etc.). 3. The current context and business priorities that relate to the decision. 4. The decision and what will be done because of the decision. 5. The consequences of making the architectural decision. ADRs are best stored in the revision control system alongside the code that they relate to, keeping the context with the code.

Explaining technical issues to PMs or stakeholders is a balancing act. Too much detail, and eyes glaze over. Too little, and the impact gets lost. I've learned (often the hard way) that it's not just about what's broken - it's about why it matters. ❌ "this API is throwing a 500" ✅ "this bug is blocking 30% of users from checking out" ❌ "refactoring will improve code quality" ✅ "this change will cut future dev time in half on this feature" The goal isn't to dumb things down - it's to connect the dots between the technical and the tangible. The best communicators I've worked with don't just know how systems work, they know how to explain why it matters to the people who care about outcomes. How do you approach that balance?

Documentation isn't late. The product is. I posted last week about why documentation gets delayed. 40 professionals responded. Not one blamed the writing. The real answers: "Asking a technical writer to produce complete documentation without even providing access to the software." "Features that didn't make it into the preproduction environment during release week." "The customer requested a redesign a third of the way through the project." "They pushed this update live last night, documentation needs to be updated now." Am I missing something here, or is there a pattern forming? Writers are being asked to document products that don't exist yet. Then blamed when the docs aren't ready on time. Here's what's actually happening: Engineering ships features up to the hour of release. Writers get zero stable ground to document against. Screenshots become obsolete before review. And when a feature gets pulled last minute, nobody tells the writer who just spent two weeks documenting it. The fix isn't faster writing. It's earlier involvement. One commenter nailed it: make documentation part of the definition of done. Not a task that starts after development ends. A gate that runs alongside it. When writers get access to preproduction environments, participate in sprint demos, and see feature changes as they happen, documentation ships on time. Not because anyone wrote faster. Because someone finally gave them something stable to write about. When does your documentation team first see the product they're supposed to document? #TechnicalWriting #Documentation #ProductDevelopment #Agile #ProcessImprovement

I just told a client their beautiful documentation was actively hurting adoption. They thought I was crazy. Then I showed them why isolated docs create more problems than they solve. I love great docs. I write them for a living. They still fail when they have to carry the whole product story on their own. Documentation can explain how your product works, but it cannot, by itself, guide users, onboard teams, or scale value the way you imagine. Here is the uncomfortable reason why: Most teams treat docs as the last step, a write-up before launch. That habit creates fragmented, hard-to-find content that answers a question but never builds confidence, context, or momentum. What actually works is a content ecosystem. Not a pile of pages, a system. It connects documentation with the pieces users really need across the journey: tutorials, use cases, explainers, onboarding flows, and thought leadership. When those parts share voice, structure, and intent, the product feels approachable and trustworthy because every path points somewhere on purpose. The linchpin is information architecture. IA decides what exists, how it is structured and labeled, and how people find it. Research on complex content shows that consistency takes planning and governance, not just good prose. Tekom defines IA in exactly these terms. Recent academic work frames IA as a core enabler of usability in HCI and knowledge systems. Translation: IA makes the ecosystem coherent so adoption and retention are even possible. If you still want the quick checklist, here it is: 1.⁠ ⁠Timing: Docs often arrive when a user is already stuck. Without pre-emptive content that shapes discovery and shows use cases, even clear instructions feel reactive. 2.⁠ ⁠Scope: Docs explain how, but rarely why it matters, when to use it, or how it fits for different personas. New users, power users, and business stakeholders need different guidance. 3.⁠ ⁠Continuity: Docs built in isolation from onboarding, tutorials, marketing, and support KBs create fragmentation. Without intentional links and shared architecture, people ping-pong between channels and miss critical steps. → Treat content like infrastructure or accept churn you could have prevented. →Stop shipping manuals and calling it strategy. →Design the ecosystem first, put IA at the center, then write. Your users do not ask for “docs vs blog.” They arrive with jobs and questions. Give them a system that answers those coherently. If this resonates, I just published the full breakdown and a preview of how we are solving this at scale with FireDraft, our upcoming platform for building intelligent content ecosystems. Early access is opening soon via the newsletter.

I wrote a 12‑page wiki.   Nobody opened it. We’d just finished a big refactor.   New service boundaries, new queue, new failure modes.   I stayed late three nights in a row “documenting everything.” Architecture diagrams.   Sequence charts.   Edge cases.   A full “Getting Started” guide. I hit publish.   Shared the link in Slack.   Pinned it to the channel.   Felt weirdly proud. Two weeks later, a teammate DMed me:   “Hey, how does this retry logic work?”  It was on page 3.   With an example.   In bold. Then another teammate broke a feature we’d already documented.   The exact pitfall had a section with its own heading.   They had no idea the page existed. That’s when the frustration kicked in.   Why am I writing all this if nobody reads it?   Why am *I* the “docs person” and still answering the same questions? The turning point came in a retro.   Someone said, “The docs are great, but I only find them when you send me links.”   That hurt…   But it was honest. So I changed my approach. I stopped writing “reference novels.”   Started writing tiny, focused docs: - One page per task: “How to add a new endpoint.”   - One page per incident: “What we learned from last week’s outage.”   - One page per sharp edge: “If you touch this flag, read this first.” And most important:   Any time someone asked a question that *was* in the docs, I didn’t answer in Slack with a wall of text.   I answered with:  “Good question, linking the doc we wrote for this →”   Then updated the doc if it was unclear. Over time, something shifted.   People started dropping links to docs *I* hadn’t posted.   PRs referenced specific sections.   New joiners actually started in the wiki, not my DMs. Here’s the lesson:   Documentation doesn’t fail because engineers are lazy.   It fails because it lives on an island. If you want docs people read:   Make them short.   Make them actionable.   And wire them into daily work: code reviews, templates, and incident follow‑ups. What’s the most useful doc you ever wrote that nobody saw until you forced it into the workflow? #Documentation #TeamManagement #TechCulture #HowNotToBreakProduction

𝟮𝟬 𝗣𝗵𝗿𝗮𝘀𝗲𝘀 𝗧𝗵𝗮𝘁 𝗞𝗶𝗹𝗹 𝗪𝗼𝗿𝗸 𝗖𝗼𝗻𝘃𝗲𝗿𝘀𝗮𝘁𝗶𝗼𝗻𝘀 𝗳𝗼𝗿 𝗗𝗲𝘃𝗲𝗹𝗼𝗽𝗲𝗿𝘀 (and what to say instead) You hear them in every Sprint Planning. In every Code Review. In every Incident Call. Conversations that make you think... "Here we go again." Here are the worst things to say during conversations, and how to turn them into win-wins. "It works on my machine" ❌ "Let's compare our environments to isolate the difference" ✅ "That's not a bug, it's a feature" ❌ "Let's review the requirements to align on the expected behavior" ✅ "Who wrote this garbage?" ❌ "Let's look at the commit history to understand the context behind this" ✅ "I can't fix this without a full rewrite" ❌ "Can we refactor this iteratively to improve it safely?" ✅ "That's impossible" ❌ "That is highly risky given our current constraints. Here is a trade-off..." ✅ "Just deploy it, we'll fix it later" ❌ "What are the risks of deploying this now versus waiting?" ✅ "QA missed it" ❌ "We should add a test case to ensure we catch this earlier next time" ✅ "I'll just hack it for now" ❌ "If we use a workaround, let's ticket the technical debt immediately" ✅ "Why is this taking so long?" ❌ "What specific blockers are slowing us down?" ✅ "Did you even test this?" ❌ "What test scenarios have we covered so far?" ✅ "That won't scale" ❌ "Let's benchmark this to see if performance will actually be an issue" ✅ "This library sucks" ❌ "This tool has limitations. Should we evaluate alternatives?" ✅ "I don't have time to write tests" ❌ "We need to factor testing into our estimation for this feature" ✅ "That's not my job" ❌ "I'm not the best owner for this. Who handles this component?" ✅ "You're over-engineering it" ❌ "Do we need this complexity right now, or can we simplify?" ✅ "Marketing changed their minds again" ❌ "Let's clarify the scope change and its impact on the deadline" ✅ "The documentation is outdated" ❌ "Let's update the docs now so the next person doesn't struggle" ✅ "I'm blocked" (and saying nothing else) ❌ "I'm blocked by X. I've tried Y and Z. Can we pair on this?" ✅ "This meeting could have been an email" ❌ "Could we handle this update async next time to save deep work time?" ✅ "Whatever, just tell me what to type" ❌ "I want to make sure I agree with the solution before we commit to it" ✅ The key difference? One protects the ego. The other protects the product. Next time you're about to say something in a tough moment... Pause... Choose words that build up the team. —— ♻️ Repost to help others create a better engineering culture ➕ Follow me ( Anton Martyniuk ) to improve your .NET and Architecture Skills