Improve Your Writing with Three Simple Words

June 17, 2025

Imagine reading a technical design document or RFC. As you read, you notice that the language in the document is a bit confusing. For example:

Requests likely need to be authorized using standard HTTP auth mechanisms

What does this “requirement” mean? Are we using “standard” Authorization headers with base64 encoded usernames and passwords? I don’t see a mention of HTTPS. And I also don’t know what “likely” is meant to convey…

The author of the document isn’t trying to be confusing, but they lack practices and tools to help make their document effective.

A key tool that I have repeatedly turned to for help with my technical writing is RFC 2119. It’s a short one (go read it!) that provides a prescriptive set of terms and writing style to help make requirements and details clear.

I hope to convince you by the end of this article that it’s worth adopting in your own writing, too.

The Language of Requirements

RFC 2119 is really focused on one idea: giving a common language for describing requirements that are clear and enforceable.

The RFC focuses on three categories of technical writing: requirements, recommendations, and optional features.

Here’s the breakdown:

• MUST / REQUIRED / SHALL
  🚨 Non-negotiable. Skipping this breaks the spec.

• SHOULD / RECOMMENDED
  ✅ Strong advice. You can skip it, but only if you’ve got a good reason—and document it.

• MAY / OPTIONAL
  🌀 Totally up to the implementer. No pressure either way.

• NOT 🚫 The NOT keyword is used to conjunction with MUST or SHOULD language to describe behaviors that are prohibited or are a strong recommendation to avoid.

This kind of structure might seem intense - and you would be right. As the RFC describes, these terms MUST be used only when necessary to convey behaviors of the system and not fine-grained implementation specifics. Don’t overwhelm your team with a keyword in every other sentence or in places they don’t apply.

When used properly, however, the benefit of these terms gives your readers—your teammates, future you, open-source users—a powerful map to navigate your ideas.

Returning to our original example, our authorization requirements could read something like

• All HTTP requirements MUST be authorized using a Basic Authorization header.
• All requests MUST be sent using HTTPS to encrypt traffic using

When to Use

If you are thinking, “I don’t write IETF RFCs, so this doesn’t really apply to me”, I’d nudge you to reconsider. You can use these terms in all sorts of documents within your work:

• Design documents or ADRs
• API interface descriptions
• System architecture notes
• Code comments (ideally linking to related design documents)

Once your team gets used to it, it speeds up conversations as well. You can begin asking questions such as “Was that a MUST or a SHOULD?” or “Perhaps we need to upgrade this SHOULD to a MUST?“. Not only is the document itself clear, but the conversations about it are clearer as well.

Another advantage is that by using language from this RFC, you get to point to the RFC for why you are using these terms in the first place. You aren’t coming up with terms out of thin air to try to communicate your intentions. You get to borrow” ideas used throughout the IETF across their technical writing.

This can speed up your writing time while also acting as a hedge from people wondering why you choose to write “MUST” vs. “a requirement of the system” (and thinking you might be too “loud” in your document).

Tips for Using It in the Real World

If you’re going to bring RFC 2119 into your writing, here are some tips I’ve found helpful:

• 📎 Add a short note: “This doc uses terminology from RFC 2119” at the top of your spec ¹.
• ✍️ Use keywords consistently—but sparingly. Not every sentence needs a MUST.
• 🔍 During reviews, ask, “Is this clearly a SHOULD or a MUST?” It can surface assumptions quickly.
• 💬 Bonus points: use it in Slack when discussing changes.

You might get some pushback or questions regarding this language initially. That’s ok!

Practice patience and humility, teaching your team why you are using this RFC and helping people learn to read it effectively. Some teams I’ve worked on have even had workshops on reading RFCs that were remarkably helpful.

TL;DR

Using RFC 2119 terms—like MUST, SHOULD, and MAY—makes your technical writing clearer, more actionable, and easier to align on. It’s a small habit that can have a big impact on collaboration.

Happy coding (and writing)!

If you enjoyed this article, you should join my newsletter! Every other Tuesday, I send you tools, resources, and a new article to help you build great teams that build great software.

Dan Goslen is a software engineer, climber, and coffee drinker. He has spent 10 years writing software systems that range from monoliths to micro-services and everywhere in between. He's passionate about building great software teams that build great software. He currently works as a software engineer in Raleigh, NC where he lives with his wife and son.

• ← Building Advanced Software