Sign up for freeSign up

Four kinds of docs: participle clauses for clear documentation

Write clearer docs with participle clauses in this B2 English for IT lesson plan on how-to guides.

Grammar
Participle clauses: -ing for the means, having + past participle for a step done first (Having signed in, open Payments.), when + past participle (When prompted…) and dangling participles.
Topic
Developer docs for a fictional payments startup's merchant app, sorted into the four kinds Diátaxis names: tutorial, how-to guide, reference and explanation.
Activities
The story of Diátaxis and the docs' new start page, a call about troubleshooting, self-checking drills, a chat with a confused reader and open boxes, then a how-to guide to write and a talk to record.

What's inside

  1. Chapter 1Warm-up: Lost in the Docs

    • PictureUnlock
    • Spin the wheel and talk about your docsSpin the wheelUnlock
    • Study the docs vocabularyVocabularyTry it
    • Choose the word for each pictureChoose by pictureUnlock

  2. Chapter 2The Story: One Page, Four Jobs

    • Read the story of DiátaxisArticleUnlock
    • Choose the correct answer about the storyQuizUnlock

  3. Chapter 3At Work: The New Start Page

    • Read the new start page of the app docsArticleUnlock
    • True or false? Check the start pageTrue or falseUnlock
    • Sort the sentences into the four kinds of docsSort into columnsUnlock

  4. Chapter 4Listen: Where Does Troubleshooting Go?

    • Listen to Sofia and Wes split the setup docListeningTry it
    • Transcript, for the teacherUnlock
    • Choose the correct answer about the callQuizUnlock

  5. Chapter 5Grammar: Having Read the Docs…

    • Study the scheme: participle clausesGrammar schemeTry it
    • Choose the correct option to complete each stepChoose the optionUnlock
    • Fill in the gaps with the correct form of the verbFill in the gapsTry it
    • Rewrite the two sentences as one: fill in the gapsFill in the gapsUnlock
    • Is the sentence correct? True or falseTrue or falseUnlock
    • Drag the words into the gaps in the how-to guideDrag and dropUnlock

  6. Chapter 6Speak Up: Help Your Readers

    • Choose the right replies to a confused readerChatTry it
    • Open a box: what kind of doc do you need?Open the boxUnlock

  7. Chapter 7Homework: Write a How-to

    • Read your phrase bankReal-life documentTry it
    • Choose the correct option: a README for a small toolChoose the optionUnlock
    • Match the sentence halvesMatchUnlock
    • Write a how-to guide for a task you knowWriting, checked by the teacherUnlock
    • Record a talk about the best and worst docs you've usedSpeaking, checked by the teacherUnlock

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

Documentation vocabulary

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

+9 more with pictures and audio in the lessonMore words

  • explanation
  • troubleshooting
  • outdated
  • parameter
  • quickstart
  • follow the steps
  • look something up
  • skip ahead
  • get stuck

Grammar: participle clauses in documentation

Instructions often pack two actions into one sentence, and a participle clause does it in fewer words: Having signed in, open the Payments tab. Working through a merchant app's developer docs, learners pick the participle that fits each step, keep one doer for both halves of the sentence and catch the dangling participle.

Participle clauses in docs

A participle clause makes a step shorter. The doer of the participle must be the subject of the main clause.

-ing, having done, done: three participles

-ing is for the means or an action at the same time: Using the test merchant account, you can issue refunds safely. Having + past participle marks a step finished first. A past participle carries a passive meaning: Written for beginners, a tutorial lets them learn by doing.

FormUse it forExample
-ing (present participle)an action at the same time, or how you do somethingUsing the test merchant account, you can issue refunds safely.
having + past participlean action that is finished firstHaving installed the debug build, sign in.
past participlea passive meaning: the subject receives the actionWritten for beginners, a tutorial lets them learn by doing.
when / once + past participlea passive step at a certain momentWhen prompted to confirm, tap Refund again.
after / before + -ingthe order of two actionsBefore running the tests, start the emulator.

One doer for both parts

A participle clause has no subject of its own, so it borrows the doer from the main clause: Having signed in, you can open the Payments tab. In an instruction, that hidden doer is the reader: Having installed the package, restart the server.

participle clause + commasubject = the doerthe rest of the sentence

Having signed in, you can open the Payments tab.

Asking the two questions, a writer can sort any page.

An -ing clause or an -ing subject?

With a comma, the -ing clause adds the means and the doer follows: Running the script, you create a config file. Without a comma, the -ing phrase becomes the subject itself: Running the script creates a config file.

-ing clause + comma: the doer comes next

  • Running the script, you create a config file.
  • Sorting its pages, Canonical found gaps.

-ing phrase as the subject: no comma

  • Running the script creates a config file.
  • Sorting its pages showed Canonical some gaps.

Dangling participles and how to fix them

A participle dangles when the subject after the comma isn't its doer: Having installed the package, the server restarts suggests the server installed it. Put the real doer after the comma: Having read the guide, I found the steps easy, not …the steps were easy.

The dangling participle

If the subject after the comma is not the doer, the participle “dangles” and the sentence says something odd: ✗ Having installed the package, the server restarts. (Did the server install it?) ✓ Having installed the package, restart the server. In an instruction, the hidden doer is you.

Typical mistakes

  • Having install the debug build, sign in.

    Having installed the debug build, sign in.

    having + past participle, never the base form

  • Used the emulator, you can test without a phone.

    Using the emulator, you can test without a phone.

    you use it (active meaning), so use -ing

  • After installed the app, open Settings.

    After installing the app, open Settings.

    after / before + -ing

  • Having read the guide, the steps were easy.

    Having read the guide, I found the steps easy.

    the doer of “read” (I) must be the subject

From today's lesson

  • Asking the two questions, a writer can see what kind of page it should be.
  • Using the test merchant account, you can issue refunds without moving real money.
  • Having moved everything, we deleted the old file.
  • Written that way, the tutorial gets a lot shorter.
  • Generated from the code every night, the settings list is never outdated.

Try the participle clauses exercises

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

More exercises

What's in the lesson

  • 13 auto-checked exercises
  • 2 games
  • 2 teacher-checked tasks
  • 1 real-life document
  • 2 articles
  • 1 grammar scheme
  • 1 set of word cards
  • 1 audio clip
  • 1 picture
  • 1 transcript

The main objectives of this lesson are to:

  • join two steps in one sentence with a participle clause: Having installed the debug build, sign in.
  • choose the participle that fits the meaning: Using the emulator, you…, Written for beginners, the tutorial…, When prompted, …
  • spot a dangling participle and fix it: Having opened the Payments tab, you'll see a new link.
  • write a how-to guide a colleague can follow, and send a reader to the right page: skip the tutorial and go to the how-to guide

Lesson 5 of English for IT B2 · Beyond the Code belongs to unit 2, Docs people read, where learners practice writing documentation and short design docs that colleagues can follow and act on. It follows lesson 4's modal verbs for requirements (MUST, SHOULD, MAY), and lesson 6 moves on to plain English and a one-page design doc to defend in a review. Setup steps are where participle clauses do their best work.

A wheel of questions about team docs starts the warm-up, followed by twelve words, from quickstart to get stuck, each with a picture and audio, and a picture quiz. The story explains Diátaxis, Daniele Procida's framework of four kinds of docs, which Canonical adopted in 2021. Next comes the new start page of the merchant app's docs, with a true-or-false check and sentences to sort into the four kinds. Then two developers argue, in an AI-voiced call, about where troubleshooting belongs.

Five drills on the scheme check themselves: students pick participles, merge two sentences into one step and drag participles into a how-to guide. In the speaking chapter, students answer a confused reader as the author of the docs, then open boxes that ask which kind of doc a reader needs. Homework brings a phrase bank, a README drill and sentence halves to match; students then write a how-to guide for a task they know and record a talk on the best and worst docs they have used, both for the teacher to review.

Grammar:
participle clauses · dangling participles
Topic:
documentation · Diátaxis · how-to guides

Teaching tips

  • Have in-company groups bring a page of their docs: in pairs, they find a paragraph that does several jobs, as the old setup doc did, and decide where each sentence belongs.
  • Act out a dangling participle before the drills: read Having installed the package, the server restarts aloud and ask who installed it. Then the class repairs the sentence in two different ways.
  • Play the call twice: first to note where each part of the old doc goes, then to catch the participle clauses, such as Having cloned the repo and Written that way.
  • With one-to-one professionals, start from their own wiki: which page tries to do four jobs at once, and how would they split it? One of the pieces can become the homework's how-to guide.

Liked it?

Teach the whole lesson in edio

25 exercises in 7 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 B2 · Beyond the Code

24 lessons at B2 for software teams, in American English. A year on at Kestrel Cloud, a fictional payments startup, Iryna and her team estimate work, write docs and postmortems, argue trade-offs, give demos and negotiate scope. Each lesson starts from a real case, from the Apollo 11 alarms to Conway's law.See the course

  1. Unit 1 Planning and estimates

    estimates and deadlines: approximating numbers, the future continuous and perfect, likelihood

    1. Lesson 1It always takes longerApproximating numbers in estimates
    2. Lesson 2By New Year's Eve, we'll have fixed itFuture continuous and future perfect
    3. Lesson 3Let's play planning pokerLikelihood with bound to, likely to and may well

  2. Unit 2 Docs people read

    specs and design docs: modals for requirements, participle clauses, plain English

    1. Lesson 4MUST, SHOULD or MAY?Modal verbs for requirements in specs
    2. Lesson 5 · you're hereFour kinds of docsParticiple clauses in documentation
    3. Lesson 6Just a request for commentsPlain English for design docs

  3. Unit 3 Incidents and postmortems

    telling an incident without blame: narrative tenses, the passive, the third conditional

    1. Lesson 7The 1202 alarmNarrative tenses for incident stories
    2. Lesson 8Blameless by designActive vs passive voice in a postmortem
    3. Lesson 9If we had had an alert…The third conditional: a different past

  4. Unit 4 Architecture and trade-offs

    comparing options and recording decisions: contrast linkers, modals of deduction, mixed conditionals

    1. Lesson 10Your system copies your org chartContrast linkers for comparing options
    2. Lesson 11It's always DNSModals of deduction for troubleshooting
    3. Lesson 12Write down the whyMixed conditionals for looking back on decisions

  5. Unit 5 Demos and tech talks

    a clear structure on stage: signposting, cleft sentences, describing trends

    1. Lesson 13The mother of all demosSignposting language for demos
    2. Lesson 1420 slides, 15 secondsCleft sentences for emphasis
    3. Lesson 15Numbers that tell a storyDescribing graphs and trends

  6. Unit 6 Stakeholders and scope

    saying no and finding yes: diplomatic language, as long as and unless, negotiating

    1. Lesson 16Pay down the debtDiplomatic language for hard messages
    2. Lesson 17Why meetings argue about the bike shedAs long as, provided, unless and otherwise
    3. Lesson 18Yes, if…Negotiating language for scope and deadlines

  7. Unit 7 AI, security and ethics

    AI tools, passwords and team rules: be used to and get used to, past modals of deduction, purpose linkers

    1. Lesson 19Your new pair programmerUsed to, be used to and get used to
    2. Lesson 20Change your password? Maybe notPast modals of deduction
    3. Lesson 21Rules for AI at workPurpose linkers for rules with a reason

  8. Unit 8 Growing your career

    feedback, retros and goals: phrasal verbs, reporting verbs, wish and if only

    1. Lesson 22Your next levelCareer phrasal verbs and goal frames
    2. Lesson 23Feedback that helpsReporting verbs and their patterns
    3. Lesson 24Start, stop, continueWish and if only for wishes and regrets

Questions about this lesson

What are participle clauses?
Participle clauses are clauses built on a participle instead of a full verb: Using the emulator, you can test without a phone. Having signed in, open the Payments tab. Written for beginners, the tutorial skips the long history. They join two actions in fewer words, so instructions and docs use them often. The key rule: the participle's doer is the subject of the main clause.
What are some examples of participle clauses?
Good examples are steps in instructions that open with a participle: Having installed the debug build, sign in (a step finished first), Using the search box, you can find any error message (the means), Generated from the code, the reference is never outdated (a passive meaning) and When prompted, tap Refund again. The B2 English for IT lesson Four kinds of docs on edio.ai builds a whole how-to guide from them.
What is a present participle clause?
A present participle clause starts with the -ing form and has an active meaning: the subject of the main clause does the action. It gives the means or a parallel action: Using the test merchant account, you can issue refunds safely. For a step finished first, use having + past participle: Having built the app, run it on the emulator. A bare past participle is wrong here: Used the emulator, you can…
What is a dangling modifier?
A dangling modifier is a phrase whose doer never appears in the sentence, so it seems to describe the wrong thing. The commonest kind is a dangling participle: Having updated the app, the old settings disappear suggests the settings did the updating. Fix it by naming the real doer right after the comma, or by turning the phrase into a full clause: After you update the app, the old settings disappear.
How do you fix a dangling participle?
Make the participle's doer the subject after the comma, or give the clause its own subject. Having opened the Payments tab, a new link appears suggests the link opened the tab; Having opened the Payments tab, you'll see a new link is clear. In Four kinds of docs, a B2 lesson on edio.ai, a confused reader quotes this sentence in a chat.
Is it "after installing" or "after installed"?
It's after installing: after and before take the -ing form. So After installing the app, open Settings and Before running the tests, start the emulator, never After installed the app. After when and once, a past participle can give a passive step: When prompted, tap Refund again. Once installed, the debug build connects to the test server.
What are the four types of documentation in Diátaxis?
Diátaxis sorts technical docs into tutorials, how-to guides, reference and explanation. A tutorial is a guided lesson in which a beginner learns by doing; a how-to guide gives the steps for one real task; reference holds precise facts to look up; explanation gives background and reasons. The framework, created by Daniele Procida, rests on two questions: is the reader doing or understanding, and learning or working?
What's the difference between a tutorial and a how-to guide?
A tutorial teaches a beginner through a small task that works, while a how-to guide helps someone who knows the basics get one real job done. Both give steps, but the readers differ: New to the team? Start here opens a tutorial, and Fix a failed build is a how-to guide. Students sort such sentences in Four kinds of docs, a B2 English for IT lesson on edio.ai.
How do you write a how-to guide in English?
Open with a How to… title and one sentence on who the guide is for: This guide is for testers who know the app. Then give numbered steps in the imperative, with participle clauses to join actions: Having signed in, open Payments. When prompted, tap Refund again. Close with If you get stuck, ask in the team chat, and leave the reasons out: link to an explanation page instead.
How do I teach participle clauses to B2 adults?
Start from two short instructions and merge them: Install the debug build. Then sign in. becomes Having installed the debug build, sign in. With professionals, use steps from their own docs, since they write such steps at work. Then give the group a sentence that dangles and ask who does the action. The B2 lesson Four kinds of docs on edio.ai has a whole drill of sentence pairs to merge.
What's good homework for practicing participle clauses?
A good task is a short how-to guide for a job the learner knows, with four or more participle clauses, each with the right doer. In Four kinds of docs, a B2 English for IT lesson on edio.ai, the homework opens with a phrase bank and two drills that check themselves; then students write a how-to guide and record a talk on the best and worst docs they've used, both for the teacher to review.
Are there interactive exercises for participle clauses?
Yes: gap-fills that mark each verb form instantly suit participle clauses, and so do chats. Without an account, this page plays four parts of Four kinds of docs, a B2 lesson on edio.ai: a call in which two developers split a setup doc, a gap-fill with forms such as built, Using and prompted, a chat with a confused reader of the docs, and the homework's phrase bank. The other exercises are locked.
Unlock full lesson

Teach this lesson with your students

Book a demoStart free trial

No credit card required