Academy › Developer Accelerator › Module 04

Technical Communication

Writing clearly about technical work is a skill that compounds professionally — developers who can explain what they built, why it broke, and what the plan is become more visible and more trusted on every engagement. AI compresses the time it takes to produce good technical communication, but the accuracy and professional judgment behind it remain yours.

⏱ 30–35 min 3 knowledge checks Documentation, incidents, design decisions

Dev Module

Your progress

Why developers avoid writing — and what changes with AI

Most developers write well when they have to — incident post-mortems, design documents, technical specs. The barrier isn't ability; it's friction. Documentation takes time. Starting from a blank page when you have a full sprint backlog is hard to prioritise. And writing about technical work for non-technical audiences requires a translation effort that doesn't feel natural.

AI removes the blank page problem. Given your technical understanding of what something does, why a decision was made, or what happened in an incident, AI can produce a structured first draft in seconds. Your job shifts from writing to reviewing, correcting, and adding the context and judgment that only you have.

The professional dividend is significant. Developers who consistently produce clear documentation, clean post-mortems, and well-reasoned design records become more trusted and more visible on projects. They get consulted more. They get more interesting work. Technical communication is one of the highest-return professional habits a developer can build — and AI makes the cost low enough that there's no longer a good excuse for skipping it.

Audience

They need

Avoid giving them

Fellow developers

What the code does, edge cases, design decisions, API contracts, how to extend it safely

Over-explanation of obvious patterns, no context about why decisions were made

QA engineers

What changed, business rules implemented, error states, integration dependencies, testable behaviours

Internal implementation details that don't affect observable behaviour

Business analysts

What the system now does from a business perspective, limitations, assumptions made, decisions that affect requirements

Stack traces, method names, class hierarchies — business impact, not implementation

Project managers

Status, blockers, risks, what help is needed, timeline impact — in plain language

Technical detail that doesn't translate to action or decision

Business sponsors

Business impact, risk level, what it means for go-live or operations — one paragraph maximum

Any technical terminology. One sentence should communicate what they need.

Technical documentation — from code to readable context

Good technical documentation isn't a description of what code does — any developer can read the code. Good documentation explains why: why this design was chosen over alternatives, what constraints shaped the implementation, what the edge cases are and how they're handled, and what would break if someone changed this in a particular way. AI handles the "what" efficiently; you add the "why."

Prompt — technical documentation for Guidewire configuration

Context I've implemented a payment plan eligibility rule in Guidewire PolicyCenter. I need to document it for the project's technical documentation repository — it needs to be useful for developers who maintain it and QA who need to understand what to test.

Task Generate a technical documentation template for this implementation. Sections should cover: purpose and business context, implementation approach (at a high level), business rules implemented, edge cases and how they're handled, dependencies and integration points, and known limitations or deferred items.

Implementation details [paste your implementation notes — the key decisions made, business rules implemented, any deviations from original requirements, known limitations]

Format Structured document with headers. Business rules section should list each rule explicitly with the condition and expected outcome. Edge cases section should be specific — not "handles nulls" but what happens specifically when a null is encountered and why. Audience: developers and QA. Plain English — no unnecessary jargon.

Knowledge Check

AI generates a documentation section for your payment plan eligibility rule that describes exactly what the code does — the conditions checked, the return values, the null handling. The section is accurate. What is most likely missing that would make this documentation actually useful to a developer six months from now?

Correct — and this is the documentation gap that creates the most expensive maintenance problems. A developer who changes the $500 threshold because it looks arbitrary will create a defect if the threshold is actually a regulatory minimum. A developer who removes the high-risk policy restriction because the comment says "monthly plan not available" will misunderstand that "high-risk" means something specific in this insurer's product model. The "what" is in the code. The "why" — the business rationale, the regulatory context, the decisions that were made and what they depend on — only exists if you put it in the documentation. AI can structure it; only you can provide it.

Option 3 identifies what's most likely missing. Code examples are useful but secondary. The full source code belongs in the codebase, not documentation. More detail about each condition describes the "what" better — but the "what" is already in the code itself. The irreplaceable documentation value is the "why" behind design decisions: the business rationale, the regulatory constraints, what alternatives were considered, and what would need to change if the business requirements changed. AI generates accurate "what" descriptions. Only you can add the "why."

Incident communication — clarity under pressure

Incidents are when technical communication skills matter most — and when developers are least inclined to write carefully. When a production integration is failing and the PM is in your Slack channel asking for an update every ten minutes, producing a clear, accurate status communication is harder than it sounds. AI drafts the structure; you verify the accuracy.

Prompt — incident status communication

Context We have a production incident: PolicyCenter is failing to process policy renewals for a subset of policies. Business impact: approximately 200 renewal transactions blocked since 6am. I need to send status updates to two different audiences.

Task Draft two versions of an incident status update: one for the technical team (developers and QA), one for the business stakeholders (operations manager and VP).

Current status Root cause identified: a database constraint violation on the renewal processing job — a foreign key constraint added as part of last week's schema migration isn't being satisfied by a subset of legacy policy records that have an orphaned endorsement reference. We've confirmed the issue, identified 247 affected policies, and are testing a remediation script. Estimated resolution: 2-3 hours. No data loss. Affected policies can be processed manually in the interim with a documented workaround.

Format Technical version: root cause technical detail, remediation approach, affected scope, current status, next update time. Business version: what is affected (renewal processing), business impact, current status in plain language, workaround if any, estimated resolution. Business version: no database or schema terminology — what is blocked, what we're doing, when it will be resolved.

The accuracy review is non-negotiable in incident communication

AI drafts incident communications from what you tell it — which means errors in your description become errors in the communication. Before sending any AI-drafted incident update: verify the count of affected items, confirm the estimated resolution time is actually achievable, ensure the workaround described actually works, and confirm the scope statement doesn't under- or over-state the impact. An incident communication that gives the wrong scope or a resolution time you can't meet creates more trust damage than a delayed update that's accurate.

Knowledge Check

AI drafts your business stakeholder incident update and includes: "No customer data has been lost or exposed." You haven't actually confirmed this — you've confirmed no data was deleted, but you haven't checked whether the failed transactions logged any sensitive data to an error log that's accessible outside the normal access controls. What should you do?

Correct — and this is a common AI-generated incident communication failure. AI adds reassuring statements about data safety because they're common in incident templates. You're the one who actually knows what happened. An unverified data safety statement in an incident communication creates two problems: if it's wrong, you've misinformed stakeholders about a privacy incident; if you later discover a data exposure, the prior "no exposure" statement looks like a cover-up. Verify first, then state. Ten minutes of log checking before sending this communication is the professional standard. If the logs confirm no exposure, send with confidence. If they reveal an exposure, the communication changes substantially.

Option 3 is the correct professional response. "Probably true" is not the standard for a statement about data security in an incident communication. The caveat version — "we believe" — is better than a flat assertion, but still implies you've looked and found nothing. Removing the statement until verified is clean, honest, and gives you ten minutes to actually check the logs. If you confirm no exposure, add it back. If you find something, the incident scope has changed and the communication needs to reflect that. Incident communications that make accurate statements, even uncomfortable ones, build more long-term trust than ones that turn out to be wrong.

Design decision records — the documentation that pays compound interest

A design decision record (DDR) documents a specific technical decision: what was decided, what alternatives were considered, what constraints shaped the choice, and what the implications are. Most teams don't write them because they take time. Teams that do write them avoid repeating the same design conversations six months later when a new developer joins and asks "why did you do it this way?"

AI makes DDRs fast enough to actually write. You have the decision in your head; AI structures it into a document that will be useful for years. The value compounds: every future developer who reads the DDR instead of having a 30-minute "why is it like this" conversation is a return on the 10 minutes it took to write.

Prompt — design decision record

Context I've made a significant technical design decision for a Guidewire PolicyCenter integration and need to document it as a DDR for the project repository.

Task Generate a design decision record from my notes. Standard DDR structure: decision title, date, status, context (what problem we were solving), decision (what was chosen), alternatives considered, rationale (why this over the alternatives), consequences (what this decision enables and what it constrains), and review date.

My decision notes Decided to use a message queue (AWS SQS) for the PolicyCenter-to-broker-portal integration rather than a direct REST call from Guidewire. Main reason: the broker portal has variable response times (2-30 seconds) and blocking the Guidewire bind transaction for that duration caused timeouts in SIT. Alternatives considered: direct REST with increased timeout (rejected — still blocks the transaction, impacts user experience), webhook pattern where portal calls back (rejected — adds complexity and requires opening inbound network ports in Guidewire environment). SQS gives us reliable delivery, decoupled processing, and an audit trail. Trade-off: adds AWS infrastructure dependency and a delay between bind and portal notification (typically under 30 seconds, acceptable per the business).

Format Formal DDR document structure. Rationale section should clearly explain why the chosen approach is better than the alternatives for this specific context — not just generic benefits of message queues. Consequences section must include both what this enables and what it constrains for future development.

Knowledge Check

Your team lead reviews the AI-generated DDR and notes that the "consequences" section only covers positive consequences — what the SQS approach enables. What should you add, and why does it matter?

Correct. A DDR that only documents benefits is advocacy, not documentation. The value of a DDR is that it tells a future developer not just what was decided, but what constraints that decision creates — so they can make informed choices about whether to extend the same pattern, work within it, or reconsider it for a new requirement. "Future developers must understand the asynchronous pattern" is exactly the kind of constraint that, if undocumented, causes a new developer to extend the integration synchronously and create a hidden dependency on the queue being real-time. AI often generates optimistic documentation — your review adds the complete picture, including the uncomfortable parts.

Option 3 is the correct response. Withholding negative consequences undermines the DDR's purpose — a future developer making decisions based on an incomplete record will make worse decisions. Framing them as risks to mitigate is better than omitting them, but they're not risks — they're actual consequences of the decision that already exist. Code comments are less discoverable than DDRs and may not survive refactoring. The consequences section of a DDR should be complete: what it enables and what it constrains. The constraints are often more important for future decision-making than the benefits.

Module summary

✅

Audience-first communication

Different audiences need different things from the same technical event. AI adapts structure and language; you ensure accuracy for the specific audience. Never send AI-drafted technical communication without verifying every claim against what you actually know.

✅

Documentation: what + why

AI generates accurate "what" descriptions from code. Only you can add the "why" — design rationale, business constraints, regulatory context, alternatives considered. The "why" is what makes documentation valuable for future developers; the "what" is in the code.

✅

Incident accuracy over speed

Incident communications with unverified statements create larger problems than delayed accurate ones. Verify scope, counts, estimated resolution, and any safety/security claims before sending. AI drafts fast; verification is non-negotiable.

✅

DDRs: complete consequences

Design decision records that only document benefits are advocacy, not documentation. Add constraining consequences — what this decision prevents or complicates in the future. That's what makes a DDR valuable for the next developer who needs to make a related decision.

One module left

Module 05 — Your AI-Augmented Developer Practice — brings it together. Daily habits, market positioning for premium engagements, and a readiness self-assessment across all five modules.

✓

Module 04 Complete

Technical Communication is done. Continue to Module 05: Your AI-Augmented Developer Practice.

Back to Pathway Continue to Module 05 →