Sign up for freeSign up

Just a request for comments: plain English for design docs and RFCs

Write design docs in plain English with this B2 English for IT lesson plan on RFCs and design reviews.

Grammar
Plain English moves: active verbs when the actor matters (The script deletes old logs.), verbs instead of nouns (decide, not make a decision), short sentences and everyday words in place of filler.
Topic
A one-page design doc on refund reasons for a fictional payments startup's merchant app, with words such as draft, non-goal, rationale and rule out.
Activities
The first RFC's story, a design doc and its review, self-checking drills, a chat with a reviewer and review role cards, then a design doc to write and defend aloud.

What's inside

  1. Chapter 1Warm-up: Docs at Work

    • PictureUnlock
    • Spin the wheel and talk about your docsSpin the wheelUnlock
    • Study the words for design docsVocabularyTry it
    • Look at the pictures and choose the wordChoose by pictureUnlock

  2. Chapter 2The Story: A Request, Not an Order

    • Read the story of the first RFCArticleUnlock
    • Choose the correct answer about the storyQuizUnlock

  3. Chapter 3At Work: A One-Page Design Doc

    • Read Iryna's design docArticleUnlock
    • True or false? Check the design docTrue or falseUnlock
    • Choose the plainer version of each sentenceQuizUnlock

  4. Chapter 4Listen: The Design Review

    • Listen to Iryna and Daniel's design reviewListeningTry it
    • Transcript, for the teacherUnlock
    • True or false? Check what you heardTrue or falseUnlock

  5. Chapter 5Grammar: Say It Plainly

    • Study the scheme: plain EnglishGrammar schemeTry it
    • Fill in the gaps: turn the noun into a verbFill in the gapsUnlock
    • Fill in the table: make the verb activeFill in the tableTry it
    • Drag the plain words into the gaps: cut the fillerDrag and dropUnlock
    • Choose the best way to split each long sentenceQuizUnlock
    • Choose the plainer option in Iryna's rollout planChoose the optionUnlock

  6. Chapter 6Speak Up: Defend Your Doc

    • Choose the right replies to a reviewerChatTry it
    • Open a box: role cards for the design reviewOpen the boxUnlock

  7. Chapter 7Homework: Your Own Design Doc

    • Read your phrase bankReal-life documentTry it
    • Do you remember? Choose the correct answerQuizUnlock
    • Is the sentence correct? True or falseTrue or falseUnlock
    • Find the matching pairs: words and meaningsMemory gameUnlock
    • Write a one-page design docWriting, checked by the teacherUnlock
    • Record yourself defending your design docSpeaking, checked by the teacherUnlock

26 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.

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

  • an alternative
  • a non-goal
  • a rationale
  • filler
  • wordy
  • concise
  • flesh out
  • rule out
  • rephrase

Grammar: plain English for design docs

Plain English, often called plain language, lets a busy reviewer read a design doc once and know who does what. Working on a one-page doc about refund reasons, learners trade heavy, passive sentences for active ones, pull verbs out of nouns, cut the filler and keep each sentence to one idea.

Plain English: who does what, in short sentences

Write so a busy reviewer can read it once and act. Concise beats impressive.

Who does what: active verbs

Plain English starts with the actor: name who acts, then give the verb. Old logs are deleted by the script becomes The script deletes old logs. The order is who, does what, to what, then why or when: We ruled out free text because reports can't group it.

Six moves from heavy to plain

MoveHeavyPlain
Use an active verb when the actor mattersOld logs are deleted by the script.The script deletes old logs.
Use a verb, not a nounWe will make a decision on Friday.We will decide on Friday.
Choose everyday wordsThe app utilizes the reason field.The app uses the reason field.
Cut the fillerin order to group refundsto group refunds
One idea per sentence, 15-20 words at mostThe merchant picks a reason, which is then sent to the API by the app.The merchant picks a reason. The app sends the reason to the API.
Name the subject, not a vague itIt is then saved, and it is shown to support.The API saves the reason. Support sees the reason in the report.

A plain sentence

whodoes whatto whatwhy or when

The merchant picks a reason before they confirm.

We ruled out free text because reports can't group it.

Verbs hidden in nouns

Heavy writing hides the action in a noun: make a decision, carry out an investigation, give approval. Pull the verb back out, and the sentence gets shorter: We will decide on Friday. We investigated the crash.

  • make a decision → decide
  • carry out an investigation → investigate
  • give approval → approve
  • provide a description → describe
  • have a discussion → discuss
  • make an improvement → improve

Everyday words instead of filler

Filler adds length but no meaning, so swap it for the everyday word: use for utilize, to for in order to, because for due to the fact that, before for prior to. Concise beats impressive in a doc people read between meetings.

  • utilize → use
  • at this point in time → now
  • in order to → to
  • due to the fact that → because
  • prior to → before
  • in the event that → if
  • with regard to → about
  • a significant number of → many

When the passive is fine

Plain English doesn't ban the passive. It fits when the actor is unknown, obvious or unimportant: We ruled out the note field because it is printed on the customer's receipt. Who prints the note changes nothing, so the passive stays.

When is the passive fine?

Use the passive when the actor is unknown, obvious or doesn't matter: “The note is printed on the receipt.” Use the active when the reader needs to know who acts: “The app sends the reason.” In a design doc, readers usually need to know who does each step.

From Iryna's design doc

  • Merchants can't say why they refund a payment.The problem in one sentence: who and what.
  • The merchant must pick a reason before they confirm.Active verb: the actor matters.
  • We ruled out the note field because it is printed on the customer's receipt.Passive is fine here: who prints it doesn't matter.
  • One more tap makes refunds slower.Short and concrete.
  • If more than half of the reasons are Other after a month, we will change the list.A clear rule, not “changes may be considered.”

Typical mistakes

  • Refund reason selection screen design update

    We are updating the screen where merchants pick a reason.

    Noun pile-up: turn it into a sentence with a verb.

  • The reason is picked, and then it is sent and saved.

    The merchant picks a reason, and the app sends the reason to the API.

    Passive chain: say who does each step.

  • The app sends the reason to the API, and then it shows it.

    The app sends the reason to the API. Then the app shows the reason in the refund details.

    Vague it: name the thing when two nouns could fit.

  • We carried out an investigation of the crash.

    We investigated the crash.

    A verb hidden in a noun: use the verb.

Try the plain English 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
  • 3 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:

  • turn a passive chain into active sentences when the actor matters: The app sends the reason to the API.
  • use the verb instead of a noun and cut the filler: We will decide on Friday. We need the reason to group refunds.
  • split a long sentence into short ones with one idea each, and name the subject instead of a vague it
  • write a one-page design doc with a problem, a proposal and non-goals, and defend it in a review: That's a non-goal for now.

Lesson 6 closes unit 2 of English for IT B2 · Beyond the Code, Docs people read, and carries the unit's work task: write a one-page design doc and defend it in a short review. It builds on lesson 4's modal verbs for requirements and lesson 5's participle clauses, which return in the homework's unit review; unit 3 then turns to incidents and postmortems. Reviewers are busy, so every extra word costs.

The warm-up brings a wheel of questions, twelve words with pictures and audio, from draft to rule out, and a picture quiz. The story tells how RFC 1 got its modest name in 1969, and how RFC 3 asked for notes that were timely rather than polished. At work, students read a one-page design doc on refund reasons and its wordy first draft, then choose the plainer version of six sentences. In an AI-voiced review, a product manager pushes to add the web dashboard to the first release.

After the scheme come five self-checking drills: nouns to turn into verbs, a table of passive sentences to make active, filler to replace, long sentences to split and a rollout plan to make plainer. Students then defend the doc in a chat with a reviewer and take role cards, from the product manager to the security reviewer. Homework reviews the unit's grammar in self-checking drills and a memory game, then asks for a design doc and a recording that defends it, both for the teacher to review.

Grammar:
plain English · active verbs · verbs instead of nouns
Topic:
design docs · plain English · the first RFC

Teaching tips

  • Start with the wordy first draft on the board: teams race to say it in fifteen words or fewer, then compare their version with the Problem section of the finished doc.
  • Play the review twice: first for each challenge the product manager raises, then for the plain answers, such as That's a non-goal for now and We ruled that out.
  • Let in-company learners defend a real change: one presents a small feature or process change from their team, and the others take role cards such as the tester or the support lead.
  • One-to-one, play every reviewer yourself: switch role cards after each answer, so the learner defends one doc against the product manager, the designer and the security reviewer in turn.

Liked it?

Teach the whole lesson in edio

26 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 5Four kinds of docsParticiple clauses in documentation
    3. Lesson 6 · you're hereJust 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 is plain English?
Plain English, also called plain language, is writing a reader can understand on the first read. It names who does what with active verbs, uses verbs instead of nouns, keeps one idea per sentence and picks everyday words: The merchant picks a reason, not Reason selection is performed by the merchant. At work, it lets a busy reviewer read a design doc once and act on it.
What is the active voice?
In the active voice, the subject is the one doing the action: The app sends the reason to the API. In the passive, the subject receives the action: The reason is sent to the API by the app. Plain English prefers the active whenever the reader needs to know who acts. The B2 lesson Just a request for comments on edio.ai has students make eight passive sentences active in a table.
How do you make your writing more concise?
Cut every word that adds length but no meaning: in order to becomes to, due to the fact that becomes because, at this point in time becomes now. Then free the verbs hidden in nouns (investigate, not carry out an investigation) and split long sentences so each holds one idea. A last pass helps too: read the draft again and cut ten words.
How do you write in plain English?
Ask who does what, to what, and why or when, then write the sentence in that order: We ruled out free text because reports can't group it. Keep sentences to 20 words at most, name the subject instead of a vague it, and choose use over utilize. The B2 English for IT lesson Just a request for comments on edio.ai teaches six such moves from heavy to plain.
Is it wrong to use the passive voice in plain English?
No: the passive is fine when the actor doesn't matter, is unknown or is obvious: The note is printed on the customer's receipt. Switch to the active when the reader needs the actor: The app sends the reason, not The reason is sent. Chains of passives are the real problem, because The reason is picked, and then it is sent and saved hides every actor at once.
Is it better to write "decide" or "make a decision"?
In plain English, the verb wins: decide, not make a decision. Nouns built from verbs, called nominalizations, make sentences longer and hide the action: We carried out an investigation of the crash becomes We investigated the crash, and give approval becomes approve. Keep the noun only when the thing itself is the topic: The decision is in the doc.
What does RFC mean?
RFC stands for Request for Comments, a document that proposes something and asks readers to respond. The first, RFC 1, is dated April 7, 1969: Steve Crocker wrote it at UCLA for the ARPANET, and its modest label made it the start of a conversation, not an order. RFCs are still published today. Teams borrow the spirit for design docs: share a plain draft early, say what's still open and ask for comments.
What is a design doc?
A design doc is a short plan: how a change will work, and why. A one-page version can have six parts: Problem, Proposal, Non-goals, Alternatives, Risks and Open questions. Each part answers a reviewer's question in plain words, as in Merchants can't say why they refund a payment. In Just a request for comments, a B2 lesson on edio.ai, students read one such doc and then write their own.
What is a non-goal in a design doc?
A non-goal is something the project says plainly it will not do, so reviewers don't expect it: This version doesn't change the web dashboard. Listing non-goals keeps the first release small and gives you a ready answer when a reviewer asks for more: That's a non-goal for now. An option you rejected goes under Alternatives instead, with its rationale: We ruled out free text because reports can't group it.
How do I teach plain English to B2 professionals?
Rewrite one wordy sentence together before any rules: a sentence of over sixty words shrinking to Merchants can't say why they refund a payment makes the point at once. Then add one move at a time: the actor first, verbs out of nouns, filler out. Professionals can bring a ticket or an email of their own. The B2 lesson Just a request for comments on edio.ai starts from such a draft.
What's good homework for practicing plain English?
A one-page design doc for a small change at work is ideal, with one last rule: reread the draft and cut ten words. In Just a request for comments, a B2 English for IT lesson on edio.ai, a review quiz and a true-or-false check on the unit's grammar, plus a memory game with the new words, mark themselves; the design doc and a recording that defends it go to the teacher for review.
Are there interactive exercises for plain English?
Yes: rewrite drills and chats with instant feedback suit plain English well. Four parts of Just a request for comments, a B2 lesson on edio.ai, can be tried right here without an account: a design review between a developer and a product manager, a table that turns passive sentences active, a chat with a reviewer of the doc, 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