What is a pattern and how do you create one?

In 2013, Fabio Akita wrote an article that stayed in my head for quite a while: Brazilian Portuguese Is Terrible: Standard vs Pattern. The central thesis is simple, but powerful: the word “padrão” in Portuguese mixes two distinct concepts in English — standard and pattern — and this confusion affects how we think about and apply these concepts day to day.

This post is a reinterpretation of that idea, with the lessons I’ve accumulated after a few years creating and maintaining patterns in development teams.

Standard vs Pattern

In English, the distinction is clear:

Standard — a norm. Something mandatory, that must be followed without adaptation. A compliance standard.
Pattern — a template. A reusable solution to a recurring problem, that guides without being prescriptive.

The Gang of Four, who popularized Design Patterns in the 90s, made this explicit in the original definition: a design pattern is a “general reusable solution to a common problem” — not a fixed solution that can be copied and pasted without thinking.

In Portuguese, we use the same word for both: padrão. And this creates a subtle problem: when someone says “create a padrão for this”, the other person may understand “standard” (mandatory, immutable) when the intention was “pattern” (guidance, a starting point).

The problem isn’t the word — it’s what people understand by it.

Why this matters in practice

When you create a pattern as if it were a standard, you create unnecessary rigidity. The team stops thinking about the problem and starts following the procedure — even when the context has changed and the original procedure no longer makes sense.

When you create a pattern as a pattern, you’re documenting a solution that worked well and can be adapted. The team uses it as a reference, not as a bible.

The difference between the two isn’t just semantic — it affects the team’s culture.

When it’s worth writing a pattern

My rule of thumb: only write when necessary.

This may seem obvious, but in practice the temptation to document everything is real — especially in teams that just went through a problem caused by a lack of documentation. The emotional response is “let’s document it so we never let this happen again”. The result is usually a wiki with 200 pages that nobody reads.

Documentation has an unforgiving characteristic: it becomes outdated quickly. The code changes, conventions change, the team changes — and the documentation falls behind silently, sometimes becoming more harmful than useful by giving a false sense of confidence.

Before writing any pattern, it’s worth asking:

Will this be reused several times? If it’s something that happens once or rarely, it probably doesn’t need formal documentation.
Is there a better way to communicate this? Sometimes a comment in the code, a naming convention, or a code example works better than a text document.
Who will need to read this? And how often? If the answer is “one person, once”, the effort of documenting it might not be worth it.

The human problem with documentation

There’s an uncomfortable fact we tend to ignore when we create documentation: programmers are human.

Humans:

Often don’t read documentation — especially when they’re in the middle of a workflow
When they read, they read superficially and selectively
Forget what they read, especially if the pattern isn’t applied frequently

This isn’t a criticism of anyone — it’s how human attention works. The practical consequence is that a pattern needs to be self-explanatory and easy to understand. If someone needs to read three pages of context before they can apply the pattern, it’s too complex or poorly written.

A good pattern is one that someone can understand in two minutes and apply on the first attempt without needing to ask for help.

The cost nobody accounts for

Beyond the problem of updating and reading, there’s a more subtle cost: mental overload.

Every rule, every pattern, every mandatory convention is another item that the developer needs to keep in their head while working. A team with 50 documented patterns might look well organized on paper — but may, in practice, be creating a cognitive load that reduces the speed and quality of the work.

With the use of AI day to day, this has taken on a new dimension: is it worth spending an AI’s context on internal patterns? Depending on the project and the company, the answer may be yes — but this cost should also be considered. Throwing a 10-page document in as context for every prompt has a price.

The rule remains cost-benefit. Fewer patterns, more relevant, shorter.

How to create a pattern that people actually use

If after all this you’ve reached the conclusion that a pattern is necessary, here’s what I’ve learned about creating documentation that actually works:

1. Explain the why before the how

Whoever reads the pattern needs to understand why it exists. Without context, the tendency is to follow the form without understanding the intention — and then you have people following the procedure when the context has already changed.

2. Include concrete examples

Nothing replaces seeing the pattern applied. A code example, a folder structure, a filled-out template — anything tangible helps more than an abstract description.

3. Explicitly state when not to apply it

A pattern has limits. Documenting the exceptions and cases where the pattern should not be followed is just as important as the pattern itself. This prevents mechanical applications in the wrong contexts.

4. Keep it short

If the pattern needs more than one page to be explained, it’s probably documenting too much in one place. Split it up or simplify.

5. Review periodically

Add a creation date and, if possible, a review date. Documentation without a date is documentation without a validity period.

Patterns are good — with caution

To be direct about where I stand in this discussion: I’m in favor of documenting patterns. Teams that work with explicit conventions tend to be more cohesive, onboarding is faster, and architecture decisions become less dependent on one or two people.

But documentation that works is documentation created with judgment. A small amount, relevant, well written, and maintained.

A good pattern is one that frees the team to think about the important problems — not one that takes up unnecessary mental space or creates bureaucracy disguised as organization.

Reference: Fabio Akita — “Brazilian Portuguese Is Terrible: Standard vs Pattern” (2013)