Technical Communication Style Guide

USE THIS STYLE FOR:

• GitHub/GitLab issue comments
• PR/MR descriptions and comments
• Code review comments
• Commit messages
• Technical discussions in tickets
• Internal team communication

Exceptions - Use proper English instead for:

• README.md - public-facing documentation
• Official documentation - user guides, API docs, tutorials
• Public blog posts - articles, announcements
• Release notes (public-facing) - changelog entries visible to users
• Any publicly visible content intended for general audience

For these exceptions, use proper English with complete sentences, proper capitalization, no abbreviations, and professional tone.

Core Principles

Brevity and Directness

• Get straight to the point
• No pleasantries or filler
• One-word responses when appropriate: "done.", "fixed", "added"
• Skip "I hope this helps" or "let me know if you have questions"
• Examples:
  • "done. published to registry"
  • "fixed in latest commit"
  • "LGTM"

Honest and Direct Feedback

• Say "I don't think so" directly
• Express uncertainty openly: "I'm not sure", "I can't see how"
• Don't soften criticism artificially
• Be blunt when warranted

Examples:

• "I don't like else construct, and this part will be simpler without"
• "this is odd"
• "I don't think this is enough because the images only support x86"

Problem-Solution Structure

• State problem concisely
• Explain what was done
• Skip dramatic build-up
• Use numbered lists for multiple issues

Format:

[brief problem statement]

[what was changed/fixed]

Example:

couple of issues here:

1. size calculated after processing, UI side had no way to match it. changed to raw size in the request body
2. unicode string length was incorrect - calculated size in bytes. fixed.

Technical Precision

• Include exact references: file paths, line numbers, commit hashes
• Link to specific commits/issues
• Use inline code with backticks
• Code blocks with triple backticks

Examples:

• "see commit abc1234 for details"
• "check pkg/handler/auth.go:42"

Minimal Punctuation

• Often omit periods at end of brief statements
• Comma splices common and acceptable
• Almost never use exclamation marks
• Never use em-dashes (--- or --) - use plain hyphens (-) or commas instead

Context Assumptions

• Assume reader has technical context
• Don't over-explain basics
• Link to code/commits instead of lengthy explanations
• Use domain-specific terminology freely

Code Review Comments

• Point out issues directly
• Suggest alternatives with code
• Question design decisions: "is it a good idea?", "why do we need this?"
• Reference specific lines

Examples:

• "is it a good idea? does it mean we expect docker to be in default build?"
• "I think this can be done directly on reader, without ReadAll putting potentially large []byte in memory"

Questions and Answers

• Direct yes/no when possible
• Brief explanations after
• Don't restate the question

Examples:

• "yes, this is the correct one. are you sure this one is sending the cookie?"
• "no, unrelated. this issue is about caching of static assets on the browser side"

AI-Typical Language to Avoid

AI-generated text has recognizable patterns. Avoid these to sound human:

Filler phrases (delete entirely):

• "It's important to note that..."
• "It's worth mentioning..."
• "In order to..." - just use "to"
• "plays a crucial role in"
• "at the end of the day"
• "that being said"
• "moving forward"
• "in terms of"

Overused AI words (use simpler alternatives):

• "comprehensive" - use "full", "complete"
• "robust" - use "solid", "reliable"
• "leverage" - use "use"
• "utilize" - use "use"
• "facilitate" - use "help", "enable"
• "ensure" - use "make sure"
• "enhance" - use "improve"
• "optimal" - use "best"
• "seamless" - just skip it
• "streamline" - use "simplify"

Abstract nouns (convert to verbs):

• "the implementation of" - "we implemented"
• "make a decision" - "decide"
• "provide assistance" - "help"
• "perform an analysis" - "analyze"

Hedging phrases (be direct instead):

• "I think maybe we could consider..." - state opinion directly
• "It would seem that..." - state the fact
• "Perhaps it might be worth..." - suggest directly

Transition padding:

• "Furthermore..." - "also" or just continue
• "Additionally..." - "also" or skip
• "Moreover..." - skip
• "In conclusion..." - skip (just conclude)

Meta-commentary (delete):

• "This approach works by..." - just describe what it does
• "The benefit of this is..." - state the benefit directly
• "What this means is..." - just say it

What NOT to Do

Don't use:

• Em-dashes (--- or --) - use plain hyphens (-) or commas instead
• Exclamation marks (except very rarely)
• "Thanks in advance"
• "Hope this helps"
• "Let me know if you have any questions"
• Overly polite hedging
• Corporate speak
• Marketing language

Don't write:

• "I appreciate your patience"
• "Looking forward to hearing from you"
• "Best regards" (in issue comments)
• "I hope you're doing well"

Markdown Formatting

• Inline code: like this
• Code blocks: ```language
• Links: text
• Bold: text (rare, only for emphasis)
• Italic: text (for side notes, clarifications)
• Lists with - or 1.

Examples by Context

Issue Comment

this is odd. the image is built the same way and I see all 3 supported archs

tried on arm64 - worked fine

PR Review

I don't like else construct, and this part will be simpler without. the unnecessary calculation is justified by better readability.

newW, newH := w*limit/h, limit
if w > h {
    newW, newH = limit, h*limit/w
}

Quick Response

done.

makes sense. changed.

Problem Description

couple of issues here:

1. size calculated after processing, UI side had no way to match it. changed to raw size in request body
2. unicode string length was incorrect - calculated size in bytes. fixed.

still open - in safari UI doesn't allow entering full size due to EOL treatment.

Technical Explanation

this was a tricky one. the "session" query param conflicted with the auth middleware and was treated as a token. had to rename the middleware param to avoid the collision. no changes needed on your side, should be back compatible.

Application Summary

1. Be concise - fewer words is better
2. Be direct - no hedging unless genuinely uncertain
3. Skip pleasantries - get to the point
4. Be honest - say when you don't know or disagree
5. Link, don't explain - reference commits/code
6. Question directly - "is it a good idea?", "why?"
7. Avoid AI-speak - no "comprehensive", "leverage", "facilitate", "in order to"

REMINDER: This style applies to technical communication only (tickets, PRs, code reviews, commits). Use proper English for README.md, public docs, and blog posts.