Reading English Technical Documentation

The Challenge of Reading English Docs

Common problems non-native developers face when reading English technical documentation:

• Reading entire paragraphs without understanding, needing sentence-by-sentence translation
• Having to look up unfamiliar expressions, which interrupts the workflow
• Forgetting what you read, or remembering the expression but not knowing how to use it
• Finding great example sentences in docs but having nowhere to save them

Tip

DevGlish’s Paragraph Mode and quick lookup let you both understand efficiently and build your expression library.

Three Workflows

Workflow 1: Quick Lookup (Without Breaking Your Flow)

You encounter an unfamiliar phrase while reading docs and need to quickly understand it without interrupting your work.

Reading: "This design pattern leverages polymorphism
to achieve decoupling between layers."

Encountered: "leverages" — quick lookup

Steps:

1. Select “leverages”
2. Press ⌘⇧D (global hotkey)
3. DevGlish floating window appears with definition and pronunciation
4. Read it, close (⌘W)
5. Continue reading the documentation

Note

Quick lookups are not automatically saved to the Word Book. This is intentional — you may only need to understand it, not review it.

Workflow 2: Paragraph Mode (Deep Understanding)

You encounter an entire paragraph you don’t understand and need a sentence-by-sentence breakdown.

Example: A Python documentation description

Original paragraph:
"The descriptor protocol is a beautiful piece of Python that
allows you to define what happens when an attribute is accessed,
modified, or deleted. This is achieved through special methods
__get__, __set__, and __delete__, which must be defined on
descriptor objects."

Steps:

1. Copy the entire paragraph
2. Open DevGlish Paragraph Mode (menu > Paragraph Mode)
3. Paste the text
4. View Claude’s sentence-by-sentence breakdown

DevGlish Paragraph Analysis:

Sentence 1: "The descriptor protocol is a beautiful piece of Python..."
  Breakdown: descriptor protocol = a Python feature that lets you define attribute access behavior
  Key words: protocol, descriptor

Sentence 2: "...when an attribute is accessed, modified, or deleted."
  Breakdown: Three operations — read, modify, delete

Sentence 3: "This is achieved through special methods..."
  Breakdown: Achieved through three special methods (__get__, __set__, __delete__)

Summary: The descriptor protocol lets you customize attribute access behavior through special methods.

Tip

Paragraph Mode isn’t just translation — it provides structured understanding: key terms, logical relationships, and a summary.

Workflow 3: Saving Quality Expressions (Building Your Library)

While reading documentation, you discover good expressions. Save them for later use in your own code reviews or documentation.

Example:

Reading Kubernetes documentation:

"A controller watches the shared state of the cluster through the API
server and makes changes attempting to move the current state towards
the desired state."

This sentence is expressed very professionally, and you want to learn this style.

Steps:

1. Select this sentence
2. Press ⌘⇧D to open DevGlish
3. Click “Save” (pin button)
4. Tag as “technical-writing” and “kubernetes”

Saved to Word Book

Expression: "A controller watches the shared state of the cluster
through the API server and makes changes attempting to move the
current state towards the desired state"

Tags: #technical-writing #kubernetes

Later when writing PRs or technical documents, search this tag to reuse or adapt this expression.

Best Practices for Reading Documentation

1. Understand the Concept Before Diving Into Code

When encountering complex concepts:

1. Use Paragraph Mode to understand the documentation explanation
2. After understanding the concept, look at the code examples
3. If still unclear, search for YouTube explainer videos

Note

Documentation + video + code — the combination of all three is most effective.

2. Active Vocabulary Library

When encountering expressions, you have three choices:

Approach	Scenario	Example
Quick lookup (don’t save)	Only need to understand, won’t use soon	”parameterize”
Save but don’t review	Good expression, might use later	”achieves decoupling”
Save + review	Common, need active mastery	”race condition”

Tip

Only save expressions that are useful to you. Saving too many leads to information overload.

3. Adjust Strategy by Document Type

Document Type	Reading Approach	When to Save
API docs	Scan quickly, look up unfamiliar words	Parameter descriptions, common usage
Tutorials	Paragraph Mode for sentence-by-sentence understanding	Good explanation sentences, examples
Design docs	Focus on concepts, ignore details	Architecture descriptions, design trade-off explanations
Blog posts	Read paragraphs, use Paragraph Mode when unclear	Opinion expressions, best practice phrases

Using Express Mode While Reading Docs

You’ve read a paragraph, understood the meaning, and want to learn to express this concept in English yourself.

Example:

The documentation says:

"Async/await is syntactic sugar over promises that makes asynchronous
code look more like synchronous code, improving readability."

You want to explain this concept in your own words. Use Express Mode:

Input (your understanding): "Async/await is syntactic sugar over
promises that makes asynchronous code look like synchronous code,
making it easier to read"

Basic (Direct):
  "Async/await is syntactic sugar over promises that makes
   asynchronous code look like synchronous code, easier to read"

Intermediate (Natural):
  "Async/await simplifies promise-based code by making it look
   more like traditional synchronous code"

Native (Idiomatic):
  "Async/await lets you write asynchronous code that reads like
   synchronous code, without callback hell"
  Tip: Mentions the actual problem async/await solves (callback hell)

Choose Intermediate or Native, memorize the expression, and use it next time in code reviews or documentation.

Common Documentation Reading Pitfalls

Common Comprehension Errors for Chinese Speakers

Misunderstanding	Reason	Correct Understanding
”achieves” = achievement	Too literal	”achieves decoupling” = accomplishes/attains decoupling
”leverage” = lever	Too technical	”leverage X” = utilize/make full use of X
”the pattern” vs “a pattern”	No articles in Chinese	”the” = previously mentioned; “a” = a specific one
”allows X to do Y” is passive?	Actually active	”allows” takes X as the object, meaning X can do Y

Caution

English technical documentation loves the “enabling” mindset (allow, enable, make possible), which isn’t as common in Chinese expression. Pay attention when reading.

Gradually Increasing Reading Difficulty

Stage 1: Simple Documentation (Beginner)

• Django beginner tutorials
• Official API getting started guides
• Medium-difficulty blog posts

Strategy: Quick lookups + occasional Paragraph Mode

Save rate: 5-10% of new expressions

Stage 2: Medium-Difficulty Documentation

• Kubernetes official documentation
• Design docs from major open-source projects
• High-quality technical blogs

Strategy: Paragraph Mode for complex sentences, Paragraph Mode for unfamiliar concepts

Save rate: 15-20% of new expressions

Stage 3: High-Difficulty Documentation

• Academic papers (in your field)
• Complex RFCs (Request For Comments)
• In-depth technical analysis

Strategy: Read a summary or video explanation first, then read the original, using Paragraph Mode for every paragraph

Save rate: 20-30% of new expressions (all high-value)

Tip

Don’t start with the most difficult documents. Begin with simple ones and gradually level up.

Quick Reference: Three Buttons

Button	Action	Scenario
Quick Lookup (⌘⇧D)	Select word > floating window > see definition > close	Need quick understanding, continue reading
Paragraph Mode	Copy paragraph > paste > get sentence-by-sentence breakdown	Entire paragraph unclear or want deep understanding
Save (pin)	Select expression > click save during lookup	Good expression, want to review or use later

Time Investment for Documentation Reading

When reading technical documentation, time allocation:

• 50% — Understanding main concepts (quick lookups, Paragraph Mode)
• 30% — Reading code examples, following along
• 20% — Saving quality expressions, adding to Word Book

Don’t spend too much time on individual expressions. “Good enough at 80%” is fine to move on — don’t chase 100% perfect understanding.

Note

Most technical documentation is quite redundant. You don’t need to understand every sentence — understanding core concepts and code is enough.