Why I Love Writing Documentation

Bankers, especially those who work in risk like me, are frequently writing. Most of the time, we do not write well, even though we have a captive audience—the auditors, model validators, and regulators who make our writing the focus of their exams. Our poorly written materials often fail to meet the standard they expect: that these materials be sufficiently detailed and clear so someone unfamiliar with our operations can understand them.^[1]

Granted, providing detail in such a setting can feel dangerous. Knowing that an auditor or examiner will dissect every word we write makes us fear them and, by extension, writing itself. Writing with clarity can also feel treacherous; clear writing offers few hiding places.

Giving in to these fears can have consequences. We write less than we should—because the more we say in our documentation, the more questions we might invite. We also hide behind jargon and complex phrases, which can interfere with clarity. Even more important, when we write to avoid feeling vulnerable, we miss the fundamental opportunity writing provides: to think! “Writing is a form of thinking, whatever the subject,” says William Zinsser in “Writing to Learn.” This principle extends to banking. With just a few adjustments to how we approach writing, we can not only create better documentation, but we can also become more thoughtful about our work.

Writing Is Easy When Thoughts Are Clear

It’s not always clear to us when our thoughts are muddled. They seem clear and fully formed in our minds. But committing them to paper or a screen can make their true nature more apparent.

Writing is humbling in this way. Forming a coherent sentence requires a coherent thought. When writing is hard, it’s most likely because we don’t know what we want to say. “If there is trouble with a sentence,” management guru and prolific writer Peter Drucker advised, “it is not the sentence that needs straightening out. It is the thought behind it.”^[2]

But rather than beginning to write by thinking, some of us (raising hand) often fill pages by copying and pasting. In documenting a technology change, for example, I once used the exact change description found in our IT system of record. Copying and pasting is the best way to ensure consistency, I reasoned. But when I was later asked to explain the change, I was stumped. Since I was not the author of the phrase “create a control for scenarios leveraging the LCR data,” I was not 100% sure what it meant. I couldn’t even explain what LCR stood for. And the person who wrote the sentence couldn’t help me because they were on vacation.

By prioritizing consistency, I created a document I didn’t understand. A document created without understanding creates risk. This danger is amplified when we use large language models (LLMs) to draft our documents. Search results from Google Gemini might sound smart, but if no one can explain what the sentence means, you could end up looking dumb.

There is a simple alternative to copying and pasting that supports efficiency without sacrificing thought: rewriting! Rewrite the sentence in your own words based on your own thoughts.

When you write a sentence, you are much more likely to know what it means. And often the reworded version is better and more straightforward than the original. The sentence is infused with your understanding and fits into the context in which it’s needed, rather than the context from which it was harvested.

Here’s an example of rewriting from my experience working with models. The first passage, from the regulatory guidance on model risk management (SR 11-7), describes how regulators define a model. The second phrase is my rewording.

 

Original: [T]he term model refers to a quantitative method, system, or approach that applies statistical, economic, financial, or mathematical theories, techniques, and assumptions to process input data into quantitative estimates.^[3]

Re-written: A model is a tool that takes inputs, applies logic to them, and transforms them into an estimate. This estimate is known as a model’s output.

 

I’m not sure if my version makes more sense to you, but I know it makes more sense to me.

By rewriting, I taught myself what the guidance means, increasing my understanding and subject matter expertise. Colleagues often ask, “How is the term model defined?” When I respond by quoting the guidance, I am typically met with blank stares. But I can get a nod of understanding when I provide my own version. Cultivating a more robust understanding of a concept allows me to better teach the guidance to someone else. Writing requires that you understand what you are writing, which will make your readers more likely to grasp the idea.

To kick off the writing process, start by thinking. Zinsser suggests asking, “What do I want to say?” Jot those ideas down and then challenge yourself: Have you captured the main idea? Next, consider what your reader ultimately needs to know. Ask yourself if what you’ve written would make sense to someone unfamiliar with your topic. From this starting point, begin writing sentences. Review your work as you go. Ask yourself if what you’ve written follows what you wrote immediately before. Do your sentences lead you to where you need to go? What do you need to say next?^[4]

If you have trouble answering these questions—or you don’t like the answers—it could be because you are not clear on what to say. You might need more information. You might need to do more research. This awareness can show you what you don’t know, who you need to ask, and what additional analysis should be done to clarify your thoughts. Once your thinking is clear, the writing will flow more easily.

Use Jargon With Care

Of course, even when your thoughts are clear, your word choices and sentence structure could make your writing incomprehensible. Jargon is a prime example. It clutters your language with exclusionary terms—special expressions used by a particular group that have no meaning to outsiders. Bankers use jargon all the time. Zinsser uses a bank memo from the 1980s to illustrate the numbing effects of jargon:

While our efforts cannot be characterized as having had a profoundly strategic horizon, the methodology utilized to identify strategy statements was not sufficiently program oriented for implementation.

 

The sentence above is not just unclear but dehumanizing, according to Zinsser. “No wonder so many Americans hate their jobs,” he laments.^[5] Insider buzzwords like “profoundly strategic horizon” and “strategy statements” suggest that the author cared more about sounding smart than providing information to the reader.

Jargon is frustrating to read (and to write) because it is essentially a waste of time. If no one can understand what documentation says, then it’s not supporting the bank’s processes and procedures. Therefore, it has no purpose.

The other problem with jargon is that it can be a crutch—a sub-par stand-in for actual understanding. The key to writing without jargon is using words you know people will understand, words with a shared meaning. Below are examples of writing with and without jargon.

 

With jargon: The ongoing reconfiguration positions Barbara offsite to identify growth and profitability potentials beyond what is currently being realized.

Without jargon: Barbara will try to find out why we are not doing better.^[6]

 

The second sentence may sound less erudite, but at least you know what it means.

Here are two more contemporary examples of bank procedures riddled with jargon. In both examples, the first sentences come from a document on model risk I’ve read recently. The second sentences are my rephrasings using more familiar terms.

 

Original: Model risk is the risk of adverse consequences from decisions based on incorrect or misused model outputs.

Revised: Bad things can happen when we use tools we don’t understand.

Original: For models associated with these data-critical business processes, model developers and owners must liaise with the business and technical data stewards within the respective business units to establish and obtain data lineage for critical data elements (CDEs) and data quality testing results for model data used across development, implementation, and use lifecycle stages.

Revised: Model stakeholders must work together to ensure that the data used in models is well understood and documented, including how data flows from one system to another and between testing and production environments.

 

            OK, so that last sentence does use some jargon. In our work, some insider terminology is inevitable. But you can also see that the second sentence uses a lot less jargon than the first. As a result, it is better and more direct. The simple act of limiting the amount of jargon in your documents will make them clearer to readers who are unfamiliar with your topic—and even to readers who are quite familiar with your topic!

Additional Writing Tips for Bankers

So far, I’ve encouraged you to clarify your thinking and to avoid jargon when writing documentation. These are the first principles of good professional writing for bankers. As you settle down to write, I offer a few additional practices to help your writing shine.[7]

Be professional. Many qualities distinguish professional writing, but one of the easiest to incorporate is simple: Write in the third person. Instead of writing in the first person (“I sampled alerts to determine the rate of false positives”) adopt the third-person voice (“Out of 100 sampled alerts, the analysis found that 95 were false positives.”)

Anticipate questions and answer them. As you review your writing, consider the full range of questions your reader might have. Be proactive about providing answers. I read lots of documentation that does a good job of answering “what,” like “What is this policy?” However, your readers will also want to know why the bank needs the policy. When you anticipate readers' questions in advance, they will have fewer of them later.

Use the active, not the passive, voice. Sentences that use the passive voice are hard to follow, and they can sound weak because they obscure who is doing the action. For example, “Loans were granted” is written in the passive voice. This sounds timid and incomplete compared to a sentence using the active voice: “The bank granted the loan.” With the active voice, there is no ambiguity regarding who granted the loan (it’s the bank).

 The active voice is important because the purpose of our policies and procedures is to say what is being done and by whom. If we rely too heavily on the passive voice, a directive may not be clear to your readers or staff.

For example, “The model’s ongoing monitoring report is reviewed quarterly” is written in the passive voice and does not explicitly say who does the action. As a result, the person charged with the work may not be aware that they are responsible and the work might not get done. But a bank with procedures written unambiguously in the active voice will not have that problem. “The model owner reviews the ongoing monitoring report quarterly” leaves no doubt about who is responsible for reviewing the report.

 Allow enough time. Writing takes time and effort. You’ll engage in a lot of reflection and rewriting before your final text—and also your thinking—are succinct and clear. Make sure to budget this time for yourself. A former communications director at Amazon once told me that one of the company’s storied six-page memos, if done properly, takes at least two weeks to draft and finalize. Multi-page, board-approved policies can take months.

Learning To Love Documentation

You’ve made it to the end of the article. Thank you for giving me your time! Have I convinced you that banking documentation should be clear to non-bankers? Or do you still think that, because banking is technical work, it needs heavy, technical writing? “If my examiner can’t understand it,” you might be thinking, “maybe they aren’t trying hard enough!”

Perhaps. But in my experience it is not productive to hope that examiners will admit fault if they find documents unclear. I’ve learned that they are more likely to view dense, jargon-filled writing as a (not very favorable) reflection of the writer’s thinking, rather than a reflection of their own.

Throughout history, the written word has contributed more to leaps in understanding than any other technology. We rarely think of bank policies, procedures, or memos as great canons of writing. But in a banking career, this is our literature—our body of work. It conveys why and how we do what we do, and it is the best way to transfer our knowledge to other bankers over time.
            Documentation is valuable, even essential. Yet we dread the act of creating it. By viewing writing as an opportunity to learn instead of a chore, we can change this mindset, one banker at a time. We can embrace writing as a vehicle to help us broaden our understanding, improve our thinking, boost our performance as knowledge workers, and, ultimately, increase the value we deliver to our institutions and their stakeholders.

If you commit to writing and rewriting—and thinking and rethinking—the result will eventually be well-written, clear documentation that fills you with pride. Your ability to teach someone else a new concept will be stronger, and your documents will be less vulnerable to regulatory criticism. Overall, our little corner of the world will be easier to understand. What’s not to love about that?

 

^[1] This is a paraphrase from the Board of Governors of the Federal Reserve System (2011) SR 11-7: Guidance on Model Risk Management. The full quotation is “Strong governance also includes documentation of model development and validation that is sufficiently detailed to allow parties unfamiliar with a model to understand how the model operates, as well as its limitations and key assumptions.” It was accessed via this link https://www.federalreserve.gov/supervisionreg/srletters/sr1107.htm.

^[2] Drucker, Peter F, Technology, Management & Society. (New York, NY: Harper & Row Publishers, 1977), 7.

^[3] SR 11-7: Guidance on Model Risk Management, ​​https://www.federalreserve.gov/supervisionreg/srletters/sr1107.htm

^[4] Zinsser, William, Writing to Learn, (New York, NY: Harper & Row Publishers, 1988), 56.

^[5] Zinsser, Writing to Learn, 66.

^[6] Zinsser, Writing to Learn, 69.

[7] These principles are universal, but it’s important to note that I derived this list in part from the American Bankers Association’s writing handbook for students completing their Capstone strategic project at ABA’s Stonier Graduate School of Banking. These are writing tips by bankers, for bankers.