Sign up for freeSign up

Docs People Actually Read: reduced relative clauses for READMEs and API docs

Students learn reduced relative clauses and participle clauses for clear docs in this C1 English for IT lesson plan, built on a README.

Grammar
Reduced relative clauses (requests sent without a key, any call exceeding the limit), participle clauses with having + past participle, openers like If omitted, and no dangling participles.
Topic
A README and an API reference for a refunds endpoint at a fictional payments startup, with words such as the happy path, spell out and stale.
Activities
A README to read, an AI-voiced review of its first draft, self-checking drills, a support-channel chat and step-by-step explanations from open boxes; homework is a Getting started section and a recorded walkthrough.

What's inside

  1. Chapter 1Warm-up: who actually reads the docs?

    • PictureUnlock
    • Spin the wheel and discussSpin the wheelUnlock
    • Study the words for talking about docsVocabularyTry it
    • Match the terms to the situationsMatchUnlock

  2. Chapter 2Reading: the README, take two

    • Read the README: Kestrel Refunds APIArticleUnlock
    • True or false? Check the READMETrue or falseUnlock
    • Choose the correct answer about the READMEQuizUnlock

  3. Chapter 3Listening: three thousand words, zero examples

    • Listen to Sofia and Rui going through the first draftListeningTry it
    • Transcript, for the teacherUnlock
    • Choose the correct answer about the reviewQuizUnlock

  4. Chapter 4Grammar: participles that don't dangle

    • Study the scheme: participle clausesGrammar schemeTry it
    • Choose the correct participle formChoose the optionUnlock
    • Fill in the gaps: -ing, past participle or having + past participleFill in the gapsTry it
    • Fill in the table: active or passive? Then reduce the clauseFill in the tableUnlock
    • Choose the correct sentenceQuizUnlock

  5. Chapter 5Speaking: explain it like a good README

    • Choose the best replies in the support channelChatTry it
    • Open a box and explain it step by stepOpen the boxUnlock

  6. Chapter 6Homework: ship the docs

    • Fill in the gaps in the API reference with participlesFill in the gapsUnlock
    • Match the complaints to the fixesMatchUnlock
    • Write a Getting started section for a tool you useWriting, checked by the teacherUnlock
    • Record a walkthrough: setting up a projectSpeaking, checked by the teacherUnlock

21 exercises in 6 chapters. Start a 7-day free trial to open all of them, copy any part into your own lessons, and teach the lesson live.

Vocabulary

10 words and phrases from the lesson, each with a picture and audio in edio.

+7 more with pictures and audio in the lessonMore words

  • gloss over
  • revoke
  • the happy path
  • default to
  • prerequisites
  • sandbox
  • stale

Grammar: reduced relative clauses and participle clauses

A reduced relative clause drops who, which or that and keeps a participle: Requests that are sent without a key are rejected becomes Requests sent without a key are rejected. Participle clauses do the same for whole steps. Both make docs shorter and easier to skim, as long as readers can tell who does what.

Participle clauses: say more with fewer words

Docs are full of them: they're short, precise and easy to skim.

Reduced relative clauses

Drop the pronoun and choose the participle by voice. An active verb turns into its -ing form: any call that exceeds the limit → any call exceeding the limit. A passive one keeps only the past participle: requests that are sent → requests sent.

Full relative clause

  • Requests that are sent without a key are rejected.
  • Any call that exceeds the limit gets a 429.
  • Merchants who use the old API must upgrade.

Reduced: -ing (active) or past participle (passive)

  • Requests sent without a key are rejected.
  • Any call exceeding the limit gets a 429.
  • Merchants using the old API must upgrade.

-ing is active, the past participle is passive

The form shows who acts. The service calling the API makes the calls; the service called by the API receives them. That is why When called with a revoked key, the endpoint returns a 401 needs called: the endpoint is called.

-ing: the noun does it

  • the service calling the API (it makes the calls)
  • When calling the endpoint, send an Idempotency-Key. (You call it.)

Past participle: it is done to the noun

  • the service called by the API (it receives the calls)
  • When called with a revoked key, the endpoint returns a 401. (It is called.)

Three participles, four meanings

In an opening clause, -ing gives a simultaneous action, a reason or the means (Using a test key, you can try anything safely); having + past participle, a step finished first (Having installed the CLI, run kestrel login); a past participle, a passive meaning (Built on Go, the service…).

FormMeaningExample
-ingactive: at the same time, or when / whileRunning locally, the service talks only to the sandbox.
-ingactive: the reason or the meansUsing a test key, you can try anything safely.
having + past participleactive: finished before the main actionHaving installed the CLI, run kestrel login.
past participlepassive: done to the subjectBuilt on Go, the service shares code with Kestrel Pay.

Openers you'll see in every README

Docs reuse a few short openers: If omitted, the amount defaults to what is left on the charge. Once configured, the CLI remembers your key. Given (that) and Assuming (that) can take any subject.

  • When called with an expired key, the endpoint returns a 401.
  • If omitted, the amount defaults to what is left on the charge.
  • If enabled, the --verbose flag prints every request.
  • Once configured, the CLI remembers your key.
  • Given (that) live keys move real money, keep them out of Git.
  • Assuming (that) you have a test key, setup takes five minutes.

Don't leave it dangling

A participle borrows the subject of the main clause, so that subject must be the doer. Having installed the CLI, a config file is created says the file installed it; Having installed the CLI, you'll find a config file puts the reader back in charge.

Don't leave it dangling

The hidden subject of the participle is the subject of the main clause, so it must be the doer. ✗ Having installed the CLI, a config file is created. ✓ Having installed the CLI, you'll find a config file. In an instruction, the doer is you: Having installed the CLI, run kestrel login. Only fixed openers like Given (that) and Assuming (that) can take any subject.

Typical mistakes

  • Once configured, you don't need to type your key again.

    Once configured, the CLI remembers your key.

    You aren't configured: the CLI is.

  • When calling with an expired key, the endpoint returns a 401.

    When called with an expired key, the endpoint returns a 401.

    The endpoint is called: use the past participle.

  • Requests sending without a key are rejected.

    Requests sent without a key are rejected.

    Requests are sent (passive): use sent.

  • Installing the CLI, run kestrel login.

    Having installed the CLI, run kestrel login.

    Installation comes first: use having + past participle.

Commas

Put a comma after a participle clause that opens the sentence: Built on Go, the service… A reduced relative clause that tells you which noun you mean takes no commas: Requests sent without a key are rejected.

More lessons on this grammar: Relative clauses lessons and exercises

Try the reduced relative clauses exercises

Try them yourself: these are the same exercises your students do in edio.

More exercises

What's in the lesson

  • 11 auto-checked exercises
  • 2 games
  • 2 teacher-checked tasks
  • 1 article
  • 1 grammar scheme
  • 1 set of word cards
  • 1 audio clip
  • 1 picture
  • 1 transcript

The main objectives of this lesson are to:

  • cut a relative clause down to a participle: requests that are sent without a key → requests sent without a key
  • use -ing when the noun acts and the past participle when something is done to it: a flag controlling the number of retries, keys stored in plain text
  • open an instruction with a participle whose subject is the reader: Having installed the CLI, run kestrel login.
  • write a Getting started section with prerequisites and numbered steps along the happy path, each with a command

Lesson 10 of English for IT C1 · Across the Company opens the unit Docs, metrics and meetings, whose writing runs from READMEs to dashboards and follow-ups. Its reduced clauses shrink the relative clauses with who, which and that from English A2.2 · Curious Minds (lessons 25 and 26), and lessons 11 and 12 go on to trends and reporting verbs. People skim docs rather than read them, so every word a clause loses helps.

Students spin a wheel about the docs they read and trust, learn ten words with pictures and audio, from a wall of text and skim to revoke and sandbox, and match them to situations. They read the second draft of a README for a refunds API, with true-or-false and multiple-choice checks, then hear Sofia's review of the first draft, an AI-voiced dialogue about three thousand words without one example. After the scheme come four self-checking exercises, among them a table that turns full relative clauses into reduced ones. To speak, students answer a merchant's questions in a support-channel chat, then open boxes and explain a setup or an API step by step.

Homework starts with participle gaps in an API reference and a match of doc complaints to their fixes, both self-checking. Students then write a Getting started section for a tool they use and record a setup walkthrough for a new teammate, two tasks the teacher reviews.

Grammar:
participle clauses · reduced relative clauses
Topic:
documentation · APIs · developer experience

Teaching tips

  • Mine the group's own repos: each learner brings one README paragraph, underlines its relative clauses and reduces those whose pronoun is the subject.
  • Before the listening, write one dangling sentence on the board: Having installed the CLI, a config file is created. Ask who installed the CLI, then let Sofia's review answer.
  • Run a thirty-second skim test: learners get the README, find one command and one error code, and say which headings, lists or code blocks helped them.
  • Turn the support chat into live pairs: one learner plays a merchant stuck on a 401, the other explains authentication in three sentences, each with a participle or a reduced clause.

Liked it?

Teach the whole lesson in edio

21 exercises in 6 chapters, ready to teach. edio is an online platform for language schools and teachers: ready-made interactive lessons, live classes, homework and student progress in one place.

  1. Start a free trial

    7 days, no credit card.

  2. Open the lesson

    Find it in the library of 621 ready lessons. Teach it as it is, or copy any chapter into your own lessons.

  3. Teach it live or as homework

    Students work in their own accounts, in sync with you during the lesson, and the practice exercises check themselves.

Teach it free for 7 days

The whole course: English for IT C1 · Across the Company

15 lessons at C1 for people who build software, in American English, with definitions instead of translations. The people of Kestrel Cloud, a fictional payments startup, write updates, reviews, RFCs and postmortems, explain tech to non-tech colleagues and negotiate scope. Real cases include the CrowdStrike outage and the xz backdoor.See the course

  1. Unit 1 Talking to the team

    async updates, code review and plain explanations: the future perfect, hedging, cleft sentences

    1. Lesson 1Async Stand-ups: Status Updates People Can Act OnFuture forms for status updates
    2. Lesson 2Code Review Without the DramaHedging in code review
    3. Lesson 3Explaining Tech to Non-Tech PeopleIt-clefts and wh-clefts

  2. Unit 2 Shipping and incidents

    estimates, releases and outages: conditionals without if, phrasal verbs, modal perfects

    1. Lesson 4Estimates, Deadlines and Saying No (Politely)Conditionals without if and mixed conditionals
    2. Lesson 5Release Day: Rolling Out and Rolling BackPhrasal verbs and their noun forms
    3. Lesson 6Incident! Learning from the CrowdStrike OutageModal perfects and narrative tenses

  3. Unit 3 Security and design

    advisories, trade-offs and RFCs: passive reporting structures, concession and contrast, nominalization

    1. Lesson 7Security Advisory: The xz BackdoorPassive reporting structures
    2. Lesson 8System Design: Every Choice Has a CostConcession, contrast and modified comparatives
    3. Lesson 9Writing an RFC That Gets ApprovedNominalization and formal register

  4. Unit 4 Docs, metrics and meetings

    READMEs, dashboards and follow-ups: participle clauses, describing trends, reporting verbs

    1. Lesson 10 · you're hereDocs People Actually ReadReduced relative clauses and participle clauses
    2. Lesson 11Metrics, Dashboards and SLOsPrepositions with numbers, trends and approximation
    3. Lesson 12Meeting Notes and Follow-upsReporting verbs and their patterns

  5. Unit 5 Retros, interviews and AI

    looking back and ahead: wish and would rather, inversion, formal obligation and permission

    1. Lesson 13The Retro: What Went Wrong This QuarterWish, would rather and it's high time
    2. Lesson 14The Interview: Selling Your AchievementsInversion for emphasis
    3. Lesson 15AI at Work: Writing the Team's RulesObligation and permission in formal rules

Questions about this lesson

What are reduced relative clauses?
Reduced relative clauses are relative clauses cut down to a participle phrase, with no who, which or that: Requests that are sent without a key are rejected becomes Requests sent without a key are rejected. They describe a noun in fewer words, which is why API docs and READMEs are full of them. The C1 lesson Docs People Actually Read on edio.ai practices them in a README.
How do you make a reduced relative clause?
Drop the pronoun and turn the verb into a participle. If the noun does the action, use -ing: any call that exceeds the limit → any call exceeding the limit, merchants who use the old API → merchants using the old API. If something is done to the noun, drop be and keep the past participle: keys that are stored in plain text → keys stored in plain text.
When can't you reduce a relative clause?
You can't reduce a relative clause when the pronoun is the object of its clause: in the key that you created, that is the object, so you can only leave it out (the key you created). Watch single finished actions, too: the engineer who wrote the script isn't the engineer writing the script, which sounds ongoing. Repeated and general actions reduce well: the job calling the Refunds API every night.
What's the difference between a participle clause and a reduced relative clause?
A reduced relative clause tells you more about a noun, while a participle clause frames the whole action: when, why or after what. The relative clause follows its noun and needs no commas when it identifies the noun: Requests sent without a key are rejected. The participle clause usually opens the sentence and takes a comma: Having installed the CLI, run kestrel login. Both use -ing for active and the past participle for passive.
Is it "requests sent" or "requests sending" without a key?
It's requests sent without a key, with the past participle, because requests are sent: the meaning is passive. Use -ing only for a noun that acts: any call exceeding the limit. The same test fixes openers: When called with an expired key, the endpoint returns a 401, not When calling. In the support chat of Docs People Actually Read, a C1 lesson on edio.ai, Requests sending without a key is the trap reply.
What's wrong with "Having installed the CLI, a config file is created"?
The participle dangles: its subject is the wrong noun. A participle clause takes its subject from the main clause, so the sentence says the config file installed the CLI. Make the doer the subject: Having installed the CLI, you'll find a config file in your home folder. A review call in Docs People Actually Read, a C1 lesson on edio.ai, catches this very sentence.
What should a README template include?
A simple README template has a short intro and three core sections. The intro says what the tool does and where edge cases are covered. Getting started lists the prerequisites and numbered steps along the happy path, each with a command to copy. Authentication says where the key goes, and Errors lists the common codes and their fixes. The README in Docs People Actually Read on edio.ai follows that order.
How do you write a README?
Write a README for readers who skim and want to start fast: one sentence on what the tool does, the prerequisites, then numbered steps along the happy path, each with a command people can copy. Spell out every parameter's type, unit and default (2500 means $25.00), list the common errors with their fixes, and keep edge cases and background for the reference: steps first, theory last.
What are common mistakes in documentation writing?
Common documentation writing mistakes are walls of text, missing examples and vague parameters, such as amount: the amount to refund, which doesn't say dollars or cents. Docs also gloss over errors in one line or keep stale screenshots. The fixes are short sections with headings, a copy-paste example of the happy path at the top, every parameter spelled out with its type and unit, and a Prerequisites list before step one.
What does "the happy path" mean?
The happy path is the normal flow, where nothing goes wrong: a valid key, a valid charge and 201 Created on the first try. Good docs show it first, as one request readers can copy plus its response, and leave errors and edge cases for later sections or the API reference. The opposite is an edge case, such as a refund on a disputed charge.
How do I teach reduced relative clauses to advanced learners?
Begin with full clauses learners already know, then cut them: requests that are sent → requests sent, any call that exceeds → any call exceeding. Each time, ask whether the noun acts or something is done to it, to choose -ing or the past participle. In Docs People Actually Read on edio.ai, a table sorts eight clauses into active and passive before learners reduce them.
Are there interactive exercises for reduced relative clauses?
Yes: gap-fills and chats that check each answer let learners test every participle as they go. This page plays three parts of Docs People Actually Read, a C1 lesson on edio.ai, without an account: Sofia and Rui's review of a README draft, a gap-fill with -ing, past participles and having + past participle, and a support-channel chat in which students help a merchant with API keys. The other exercises are locked.
Unlock full lesson

Teach this lesson with your students

Book a demoStart free trial

No credit card required