Writing Great PRs and READMEs

Why Technical Writing Matters

In code reviews, your PR description is the reviewer’s entry point. A good PR description can:

• Help reviewers quickly understand what you did
• Reduce back-and-forth questions
• Show that you’ve thought things through
• Save your time when you look back at the history 3 months later

Similarly, a good README can:

• Help newcomers get up to speed quickly
• Reduce repetitive questions
• Make the project look professional

Tip

Technical writing isn’t creative writing. There are formulas and patterns — learn them and you’ll write well.

Standard PR Description Structure: What/Why/How/Testing

1. What (What Did You Do)

A concise summary, one sentence.

Refactor authentication flow to support OAuth2 and magic link sign-up

Or a more detailed version:

What: Refactor authentication flow to support OAuth2 and magic link sign-up

This PR replaces the old session-based auth with a stateless JWT approach,
enabling OAuth2 for easy sign-in and magic link for passwordless access.

Key expressions:

• Add X — new feature
• Fix X — bug fix
• Refactor X — rewrite code (without changing functionality)
• Optimize X — improve performance
• Implement X — implement a design

2. Why (Why Did You Do It)

This is the most commonly neglected part. Explain the context and motivation.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

Or narrative style:

Why:
Recently, we had three enterprise customers request OAuth2 support
for their SSO integration. Our current session-based auth can't handle
cross-domain SSO, so we're migrating to JWT + OAuth2.

Signs of a good Why:

• Mentions business reasons (user needs, performance, maintainability)
• Explains why the existing approach isn’t enough
• Explains why this solution is better

Caution

“Because I wanted to” is not a good Why. State the real reason.

3. How (How Did You Do It)

A high-level overview of the technical implementation. You don’t need to explain line by line (that’s the code review’s job), but reviewers need to know the overall architecture.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims
5. Added magic link generation and validation

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

Key expressions:

• Created X using Y — technology choice
• Replaced X with Y — migration
• Added X routes — new API endpoints
• Migrated X from Y to Z — data migration
• Breaking changes — backward-incompatible changes

4. Testing (How Did You Test It)

Explain how you verified this change is correct.

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Verified JWT expiration and refresh flow works correctly
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)
- Tested on staging environment with real data

Outstanding:
- QA will do full regression testing (scheduled for Thursday)
- Performance benchmarks vs old auth (will share results in comment)

Note

The “Testing” section is important — it tells reviewers you’ve already tested, so they don’t need to spend time finding bugs.

PR Description Template

Copy this and fill in the blanks:

## What
[One-sentence summary]

[More detailed description, 2-3 sentences]

## Why
- [Reason 1]
- [Reason 2]
- [Reason 3, if applicable]

## How
1. [Change 1]
2. [Change 2]
3. [Change 3]

[If there are breaking changes, state them here]

## Testing
- [What testing you did]
- [What the results were]
- [Outstanding items (if any)]

## Related
Closes #123
Depends on #456 (wait for this to merge first)

Common README Structure

Opening: What the Project Is

# ProjectName

One-sentence description of what this project does.

[A demo gif or screenshot]

Example:

# DevLingo

A macOS menu bar app that helps non-native English speaking developers
improve their English in the flow of work. Select text → global hotkey →
learn pronunciation, synonyms, grammar tips.

Installation (Getting Started)

## Getting Started

### Prerequisites
- macOS 12+
- Node.js 18+ (for backend development)
- Xcode 14+ (for macOS app development)

### Installation
1. Clone the repository
2. Follow setup instructions in `/backend` and `/MacApp`
3. Run `npm run dev` in backend folder
4. Open `MacApp/DevLingo.xcodeproj` in Xcode

Usage

## Usage

### Basic Usage
1. Select any English text
2. Press ⌘⇧D (global hotkey)
3. Learn pronunciation, examples, synonyms

### Advanced Features
- Save words to personal vocabulary
- Spaced repetition for review
- Batch import from CSV

Contributing

## Contributing

We welcome contributions! Here's how to help:

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/amazing-thing`)
3. Commit your changes
4. Push to branch and create a Pull Request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

Grammar Traps in Technical Writing

1. Tense (The Most Common Mistake)

Principle: Use present tense to describe what code does; use past tense to describe what changes you made

Mistake	Reason	Correct
”The function was created to handle X”	Sounds like historical narration	”The function handles X” or “This PR adds a function that handles X"
"The code will validate input”	Too uncertain	”The code validates input"
"We added the feature” (in a README)	READMEs don’t tell history	”This feature allows users to…“

2. Articles (Common Mistake for Chinese Speakers)

Principle: Use “a/an” for first mention, “the” for subsequent mentions; or use plurals to avoid articles

Mistake	Reason	Correct
”We refactored authentication flow”	Unclear which flow	”We refactored the authentication flow” or “We refactored authentication flows"
"Function handles case when user logs in”	Chinese-style, missing “the"	"The function handles the case when a user logs in”

3. Passive Voice Overuse

Principle: English prefers active voice. Unless you don’t want to say who did it, use active

Passive (common L1 interference)	Active (better)
“The JWT is generated by the server"	"The server generates the JWT"
"The user data is stored in D1"	"We store user data in D1"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. Subtle Synonym Differences

Word	Usage
Add	Brand new feature (didn’t exist before): “Add OAuth2 support”
Implement	Realize a known design: “Implement the design from #123”
Create	Generate a new object: “Create JWT service”
Build	Construct a system: “Build the CI/CD pipeline”
Refactor	Improve existing code without changing functionality: “Refactor auth middleware”
Optimize	Improve performance: “Optimize query performance”
Fix	Fix a bug: “Fix race condition in cache”

Using Express Mode to Review Your PR Description

After writing a PR description, run it through DevGlish Express Mode:

Example: Checking Your “Why” Section

You wrote:

Why: Users need to sign up faster

Paste into Express Mode:

Input: "Users need to sign up faster"

Basic (Direct):
  "Users need to sign up faster"

Intermediate (Natural):
  "Users are requesting a faster sign-up process"

Native (Idiomatic):
  "We've had 5 sign-up requests from enterprise customers.
   The current form takes 3+ minutes. A passwordless option
   would significantly improve conversion."
  Tip: Use data and context instead of the vague "need"

Choose “Native” and adjust:

Why: We've received multiple requests from enterprise customers for
passwordless sign-up. Current form takes 3+ minutes and users often
abandon. Magic link sign-up would improve conversion and reduce support load.

Reviewing Your README with Paragraph Mode

Use DevGlish’s Paragraph Mode to review your README draft:

DevGlish → Paragraph Mode
Input your README introduction

The system will flag:

• Sentence structure (too complex?)
• Repeated words (better synonyms available?)
• Passive voice overuse
• Unnecessary words

PR Description Quick Checklist

Before sending a PR, check:

• What section clearly explains the change
• Why section has business or technical reasons (not just “I wanted to”)
• How section covers high-level design so reviewers don’t need to read code line by line
• Testing section describes your test coverage
• No excessive passive voice
• Articles are used correctly (“the” vs “a”)
• Tense is consistent (present for code behavior, past for changes)
• Links to related issues (if any)

README Quick Checklist

• Opening sentence clearly explains what the project is
• Has a demo or screenshot
• Installation steps are clear and reproducible
• Usage examples can be directly copied
• Has contributing guidelines (if accepting outside contributions)
• Has a license
• Language is concise (not too academic or too casual)