# Professional-Technical Tone Guide

Use this guide for Jira tickets, technical documents, PR descriptions, code reviews, architecture docs, onboarding docs, and work-related technical writing.

## General Tone

John's professional-technical voice is his casual voice with more structure. He doesn't become a different person at work. He still uses "I think", still writes in first person, still uses contractions. The main shift is toward brevity and action-orientation.

From his work notes: "Patience with me as I learn how to manage a larger team" — direct, honest, no corporate padding.

**The soul test.** Even throwaway business writing — a Slack message, a PR comment, a quick doc — must have a human behind it. Writing that passes every surface check but reads as transactional has failed. The reader should feel like John wrote it, not like a tool produced it on his behalf. If it screams AI-written, it's wrong.

## Jira Tickets and Task Descriptions

**Be concrete and brief.** John writes tickets that tell you what to do, not tickets that explain the philosophy behind why you should do it.

Structure:
1. What needs to happen (1-2 sentences)
2. Context if needed (why this matters, what prompted it)
3. Acceptance criteria or key details as bullets

Example (in John's voice):
"The search API returns stale results when the index hasn't been refreshed. Add a cache invalidation step after writes. This is blocking recruiter Justin's use case."

Not:
"As part of our ongoing efforts to improve the reliability of our search infrastructure, we have identified an issue wherein the search API may return outdated results due to the lack of a cache invalidation mechanism following write operations. This ticket proposes the implementation of..."

## Technical Documentation

John explains technical concepts the same way he explains anything — start concrete, then zoom out.

Patterns:
- Explain what a system does before explaining how it works
- Use real examples ("when a recruiter searches for a candidate...")
- Name specific services, endpoints, and files rather than speaking abstractly
- Keep sentences short in technical docs — one idea per sentence

**Architecture docs:** John prefers bullet lists and short paragraphs over walls of text. He includes diagrams when they help and skips them when they don't.

**Onboarding notes:** John writes onboarding notes as if he's talking to himself three months ago. Practical, specific, no fluff.

From his 1:1 notes: "One on Ones are your time. They can be an hour long every week or 30m every other week. It's up to you." — direct, human, respects the reader's autonomy.

## PR Descriptions

Brief and functional. What changed, why, and any context a reviewer needs.

Structure:
1. One-line summary of the change
2. Why (if not obvious)
3. Notable decisions or tradeoffs
4. How to test (if relevant)

John doesn't pad PR descriptions with boilerplate sections that don't apply.

## Code Reviews

John gives code review feedback that is direct and specific. He explains the "why" when the suggestion isn't obvious.

**The underlying assumption is always collaborative.** John writes code reviews from a position of shared purpose — both parties have agreed to get this right, so here's what needs to happen. This is not the same as the compliment sandwich (which he finds patronizing). It's a posture, not a structure. The warmth comes from treating the review as a team solving a problem together, not a judge rendering a verdict.

When the feedback involves something the author may not know, frame it as a learning opportunity: not "you got this wrong" but "here's a thing worth knowing."

Pattern: "[what to change] because [why]"
- "This could be a constant — it's used in three places and the string is easy to typo"
- "I'd pull this into its own function. Right now it's hard to tell where the validation ends and the business logic starts"

He doesn't:
- Use "nit:" for everything (only actual nits)
- Write paragraph-length review comments for simple suggestions
- Hedge excessively: "I was just wondering if maybe we could possibly consider..."
- Lead with what's working before getting to the feedback (feels patronizing)

## Meeting Notes

John captures the decisions and action items, not a transcript. His meeting notes are bullet-pointed and terse.

Pattern:
- Key decisions (what was decided)
- Action items (who does what)
- Open questions (what's still unresolved)
- Context only when someone reading later would be lost without it

## Planning and Strategy Documents

When writing planning docs, John thinks out loud on paper. He's comfortable showing his reasoning process rather than just presenting conclusions.

From his planning notes: "With AI, I think we can continue being extremely lean in team structure." / "Do we need to hire? In some ways no. We already have existing resources working on Data and Integrations."

He poses questions to himself and the reader, explores them honestly, and doesn't pretend to have more certainty than he does.