Review: Polite Technical Collaboration

By the end of this lesson, you will be able to...

• Choose a modal that makes a technical comment polite without hiding the technical claim.

• Separate permission, prohibition, requirement, request, hypothesis, and committed behavior in one review thread.

• Rewrite a rough pull request comment into precise collaborative English.

Idea in one sentence: Polite technical English is not softer everywhere; it is clear about the system and careful with the person.

Core Insight

Imagine a pull request for the export API.

The code adds a staged rollout for a new export worker. It also updates the API contract for duplicate requests and optional filters. The change is useful, but the review thread has several small problems:

This is wrong. Add rollback notes. Clients shall send the optional filter.
The server maybe returns 409. Check if the old assumption is still true.

The technical concerns are real. The English is doing too many jobs badly.

Some sentences need to be firm:

The service must not expose private tokens.

Some sentences need to be permissive:

Clients may send one optional filter.

Some sentences need to be collaborative:

Could you check whether this assumption still holds?

The review skill is not "make every sentence soft." The skill is to match the modal to the job of the sentence.

The Review Situation

Here is the small pull request.

Change: route 10% of export jobs to the new worker.
Risk: rollback is not documented.
Contract: duplicate requests should return 409.
Optional input: clients can send one date filter.
Security rule: private tokens cannot appear in the response.
Open question: the design assumes the old worker is still faster for large exports.

A blunt comment might be:

Add rollback notes. The new worker will be safer. Clients shall send the optional filter.
Do not expose tokens. Check the old assumption.

This is short, but it creates avoidable friction.

It also creates avoidable ambiguity:

• will be safer sounds too certain if the rollout is only a proposal.
• shall send the optional filter makes an optional input sound required.
• Do not expose tokens is clear, but it does not name the system boundary.
• Check the old assumption is a command, not a collaborative request.

The better comment keeps the technical pressure and improves the reader's path.

The Modal Map

Before rewriting, classify the job of each sentence.

The same pull request can need several modals. That is normal.

The modal changes because the owner changes. The client owns client input. The server owns server behavior. The reviewer owns the request. The team owns the design decision.

Plain to Precise Bridge

Plain meaning:

Say the technical thing with the right strength, and ask the human thing with respect.

In this scenario:

The security boundary is not optional, so it needs must not. The date filter is optional, so it needs may. The assumption needs a teammate's attention, so it can use could you or would you.

Technical name:

This is modal choice by commitment level. The modal tells the reader whether the sentence is a rule, permission, request, option, hypothesis, or promise.

A Worked Rewrite

Start with the rough input:

Add rollback notes. The new worker will be safer. Clients shall send the optional filter.
Do not expose tokens. Check the old assumption.

Now trace the rewrite.

The output comment becomes:

Would you add rollback notes before approval? Routing 10% of exports first
would reduce rollback risk, but it would add one deploy window. Clients may
send one optional date filter. The response must not include private tokens.
Could you check whether the old-worker speed assumption still holds for large
exports?

The naive failure was not only tone. The rough comment mixed commitment levels:

will = promised result
shall = formal obligation
command = direct order

The revised comment separates them:

would = hypothetical result
may = permission
must not = prohibition
could you / would you = polite request

So far, the rule is simple:

Be firm with the system boundary.
Be careful with the human request.
Be honest about evidence.

Common Confusions

Confusion: polite means vague

Why it is tempting:

Learners often soften every word when they want to sound respectful.

Better model:

Polite does not mean unclear. This sentence is polite and specific:

Would you add rollback notes before approval?

It names the action and the condition.

Confusion: strong technical judgment should sound harsh

Why it is tempting:

Security, reliability, and API contracts often need firm language.

Better model:

The system boundary can be firm while the request stays respectful.

The response must not include private tokens. Could you add a test for that case?

Confusion: shall makes a sentence more professional

Why it is tempting:

Shall sounds formal.

Better model:

Formal is not always clearer. In normal review comments, must, may, will, and would usually show the commitment more directly.

Trade-offs and Limits

Precise modal choice improves trust. The reader can see what is required, what is allowed, what is forbidden, and what is only expected.

The trade-off is that you must slow down for one small classification step before writing. That costs a few seconds.

It does not solve every collaboration problem. A technically precise sentence can still be unhelpful if it arrives without context, evidence, or priority.

You can see the boundary when a teammate asks:

Is this a requirement, a suggestion, or just a concern?

That question means the modal did not carry enough meaning, or the sentence needs one more concrete detail.

A useful repair is to add the missing evidence, not to add more polite words.

Could you check the large-export benchmark before approval?

That sentence gives the teammate a clear test. It also shows why the request matters.

Check Your Understanding

Check: Which sentence is both polite and technically specific?

A. Could you check whether this assumption still holds for large exports?
B. Check thing.
C. Maybe maybe this assumption, if possible.

Think first, then reveal.

Answer: A is best. It asks politely, names the action, and names the technical scope.

Check: Which sentence should stay firm, not soft?

A. The response might maybe avoid private tokens.
B. The response must not include private tokens.
C. Would private tokens be included if convenient?

Think first, then reveal.

Answer: B is best. A security boundary needs prohibition, so must not is clearer than soft uncertainty.

Practice

Rewrite this rough review comment:

This rollout is risky. Add docs. Clients shall send one optional filter.
The server maybe returns 409. Check if the assumption is true.

Model answer:

Would you add rollback notes before approval? Routing 10% of exports first
would reduce rollback risk, but it would add one deploy window. Clients may
send one optional date filter. The server will return 409 for duplicate
requests after this contract is implemented. Could you check whether the
old-worker speed assumption still holds?

Why this works:

• Would you and Could you make the human requests collaborative.
• Would reduce keeps the rollout benefit hypothetical.
• May send keeps the filter optional.
• Will return fits committed server behavior only after the contract is implemented.

Daily Practice Lines

Read these lines once or twice during the day:

Could you check whether this assumption still holds?
The response must not include private tokens.
Clients may send one optional date filter.

The first line is the review line for this lesson.

The second line reviews prohibition from lesson 013.

The third line reviews permission from lesson 014.

Resources

• [ARTICLE] Cambridge Dictionary Grammar: Modals
  • Link: https://dictionary.cambridge.org/grammar/british-grammar/modals
  • Focus: Use it as a reference for modal meaning, then test each modal in a technical sentence.
• [REFERENCE] RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
  • Link: https://www.rfc-editor.org/rfc/rfc2119
  • Focus: Notice how formal documents define requirement words instead of relying on tone alone.
• [ARTICLE] Microsoft Writing Style Guide
  • Link: https://learn.microsoft.com/en-us/style-guide/welcome/
  • Focus: Use it for clear technical wording that respects the reader's task.

Key Takeaways

• Polite technical collaboration keeps the person respected and the system claim precise.
• Use must not for forbidden behavior, may for permission, would for hypothetical results, and will for committed behavior.
• Use could you or would you for requests, but keep the action, evidence, owner, or deadline visible.
• When a sentence feels wrong, ask what job it has: rule, permission, request, option, hypothesis, or promise.