The Importance of Writing in Software Engineering

The Importance of Writing in Software Engineering - Interview with Erica Greene (Senior Engineering Manager, Etsy)

What’s the importance of writing when it comes to running your engineering team?

You read documents all the time. You also write them a lot of the time. You often ask others to write documents for you, and you read those as well.

Writing great documents can make your proposals more likely to be accepted, your professional relationships smoother, and your colleagues happier.

It makes everything better, and rest assured: everyone will take note of things going well around you.

In this post, we take a deep dive into the importance of writing in engineering management with Erica Greene, Senior Engineering Manager at Etsy. She shares her stories, her tips to improve your own writing skills, and others’ as well. Based on episode 49 of the Level-up Engineering podcast hosted by Karolina Toth.

This post covers:

• The importance of writing in management
• The importance of writing in software engineering
  • Engineers work with lots of documents
  • Example: Writing a project plan
• The importance of writing in meetings
  • Prepare for meetings
  • Keep tack of discussions
  • Replace meetings
• Improving your writing skills as a manager
  • Find an editor
  • Follow the editing process
• Stories about improving writing skills
• Writing tools for engineering managers
• Common mistakes
  • Complicated sentences
  • Too much or not enough context
  • Fear of writing badly
• Teaching your team the importance of writing
  • Define the types of documents
  • Provide templates
  • Provide mentoring
  • Emphasize: writing is real work
• Bonus advice
• About Erica Greene

What is the importance of writing in management?

Writing is underrated in the engineering management literature. In my experience, the people who express themselves in written communication well have an advantage in the software industry. It’s increasingly true in the era of remote engineering teams when everyone is forced into remote meetings all the time.

Writing clear documents is a way to scale your influence, improve communication, and improve everybody’s quality of life around you.

Why is writing important in software engineering in general?

Engineers work with many documents

In software engineering, you work with many written documents. They can be at different levels of granularity, like operational documents, pitches, proposals, etc.

It’s the engineering manager’s job to coach their team to write good documents. If you fail to do that, you have to keep running around and get every detail directly from them. Teaching your team to write high quality documents makes your life easier.

Example: Writing a project plan

A project plan is basically the technical version of a policy memo.

You’re proposing an execution plan, and you need to get others on board with it. You want to communicate the necessary technical work, the risks and the options you’ve evaluated to everyone involved. The goal is to get everyone on the same page before writing any code.

I write the document as if I need to explain in detail what my team is doing. They contain these elements for the sake of transparency:

• Title
• Authors
• Date of the last edit
• List of resources at the end

Here are some guidelines to writing them well:

• Start with a summary
• Outline options
• Address risks
• Stick to the point
• Use high-level diagrams
• Don’t go over four pages

Summary

The summary is not a background; it’s just a paragraph of the document's goal. For example, “We are proposing to rewrite this system. The project is supposed to take three to six months.”

Main points

In the main points, cover the necessary background for the reader. When it comes to project plans, the readers tend to have technical knowledge, but they usually don’t have the context your team members do. You don’t have to make it so detailed that a random person on the street could get the full picture just by reading it.

Visual elements

When it comes to a technical proposal, a diagram is almost always helpful. In a project plan, you can cover the operational side of your proposal. For example, you may visualize the milestones with success criteria, calling out risks and other options.

Why is writing important in meetings?

Working with remote or hybrid team models forces you to have extra meetings. In my experience, sitting in remote meetings all day isn’t fun.

You can use writing to make meetings more efficient, and even eliminate some of them.

Write to prepare for meetings

I prefer to call meetings when a decision requires a conversation. Meetings are more engaging when you have a substantial topic to dig into. Writing a document in advance can help you facilitate that.

Write to prepare yourself

You may not even have to share your document with anyone. Writing down your thoughts in itself forces you to clarify them, and prepares you to have a more productive conversation about the topic.

Write to prepare everyone

You often spend extra time in meetings on explaining the context and the proposals in question. The problem with doing this in every meeting is that it doesn’t scale. You have to keep repeating it every time someone misses an update or a new person joins the discussion.

You can turn this into a document, make it available to participants, and have them come prepared.

I often ask people to write documents. They may be overwhelmed at first, because they think they need to make it highly formal, but they don’t. It takes 15 minutes to write down your points, add some bold or bullet points, put a title and your name on it, and send it around.

Most of these documents have a short life cycle. They’re tools to preserve the discussion, and to move the project forward.

Amazon has an interesting practice for this. They send everyone documents to prepare for meetings, and they provide a set amount of time at the start of each meeting for everyone to read them. This way, everyone is up-to-date, and they don’t have to clear time for preparation outside the meeting.

Write to keep track of discussions

Points and questions are easier to keep in mind and answer in a document or in comments. It provides structure and a process, depending on your engineering culture.

Write to replace meetings: Story from Etsy

Recently, I had a disagreement with a project manager regarding a project. We had a meeting about it and it was productive, but we didn’t manage to completely resolve the conflict. He suggested that we continue the discussion in a document.

We wrote down the points that we agreed on, and the points we disagreed about, and we started a back and forth. He wrote his response and sent it to me, and I could answer when I found some time, and then send it back. We resolved the conflict in about four to five rounds.

It was a misunderstanding, and we came to a compromise. It was an efficient way of working out a conflict in written format, which we probably wouldn’t even have tried pre-pandemic, working fully on-site.

How do you improve your writing skills as a manager?

There are many different types of writing. You may write documentation, emails, feedback, comments in a code review or something to a broader audience.

You need to learn to navigate the corporate world and master the protocols and the expectations of different types of writing. No one tells you that when you start your career.

I remember being scared of writing in my first job. I had no clue how formal I should make the emails, and who was going to read my documents. It varies between companies, so you have to pick up on it as you go.

Find an editor

An editor can help you get better in any type of writing. You need someone to correct you and tell you where you need to improve your writing skills.

It may seem silly to have somebody edit an email. On the surface, it seems to make more sense to ask someone to edit a blog post, but it’s great to involve an editor in anything you write.

When I’m sending an email to a broader audience, I write it in a Google Doc, and show it to people to get feedback on that email before it goes out. Early in my career, I had people edit almost all my written communication line by line. That’s the best way to improve your writing.

Ask for help from the people around you

Whether it’s an email, a blog post, a document or anything else you’re writing, going to your manager is a good first step. They tend to write more, so they can likely help. My manager has written books, and he has worked with professional editors; so he’s a good writer.

You may also find strong writers on your team who write more as a part of their everyday job. Product managers usually write a lot, or you may find a peer who’s good at writing. People are usually flattered when you ask for their advice, so don’t be shy.

Go through the editing process

You learn more about writing if you follow the editing process live or ask your editor to walk you through the changes they made. Someone could make the text better by correcting mistakes or changing the sentence structures without you learning what rules they applied. You need to understand this to improve your writing.

The goal is to become a better writer. Ask for help, and pick their minds about the rules they apply when writing.

Story from Etsy

At Etsy, I recently worked with someone at the company on revamping our external blog, called Code as Craft. We hired a  professional technical editor and involved him in all phases of the process. He helped us write internal guidelines for our colleagues to write blog posts, and he did the editing too.

I would love to have a full-time editor on staff. People at tech companies need to write different kinds of documents, emails, etc. all the time. They often don’t feel confident about it, but an editor can help by holding workshops for them.

Writing is a real skill. When it comes to writing in the workplace, no one expects you to write like Shakespeare, but it’s helpful to provide best practices to follow.

What have you personally done to improve your writing skills?

Use an editor

I ask others to read my writing before I send it out. Sometimes I even do this with my partner when it comes to personal matters; he’s a good writer too.

Take external courses

I joined a fellowship program at the Aspen Institute, where I learned a lot about writing policy memos. We wrote many policy memos, and they edited our writing in detail. This made me a better writer; I became more aware of every single word.

Story from Clinton’s office

The woman who ran the fellowship program used to work for Hillary Clinton when she was a senator. She said that Hillary went home every night with a binder of 100 policy memos that her team wrote.

She used these well-written memos to make hundreds of decisions. They highlighted what was happening, the decisions to be made, and a recommendation. She could just go through them, and if she disagreed with anything or had questions, she could dig into the memo for more details.

This is how decisions are made at scale.

What are the tools and platforms you use to write as a manager?

Use spell check

Any text editor of your choosing will do, just make sure it has spellcheck. I write my emails in Google Docs for the spell check, especially when I’m about to send it to a broader audience.

It’s useful even when you’re writing a longer Slack message or an announcement. You don’t want to press send accidentally and share a half-baked message.

Use a drawing tool

A drawing tool is a must in technical writing because visualizing abstract ideas is essential to writing a good document. It improves engagement and simplifies complex concepts.

I often use Google Drawings to keep things simple. Others like using Lucidchart or similar tools. They all do the trick.

What are the common mistakes managers need to avoid in their writing?

No visuals

Take the time to create a nice visual for your documents, and you’ll have an easier time explaining anything.

Complicated sentences

I often see people use a lot of parentheses, slashes, and long sentences. Avoid using these.

Stick with short sentences, periods, and punctuation; you barely ever need to use parentheses.

Too much or not enough context

When it comes to writing, consider your audience first, and write for them. Provide enough context for them to get their input on the document. It’s difficult to balance because the right amount of context varies.

People often don’t keep that in mind and go too deep, or they keep it too high level.

Separate in-depth and high-level sections

You might get into the technical details, or you might stick to high-level explanations. Just avoid doing both in the same part of the document.

The different approaches target different people. You can do both within one document, just structurally separate them into different sections. Open with the high-level view, and put the lower level details later to provide an option for a deep dive.

Be aware that different people will be reading these different sections.

Fear of writing badly

Write bad first drafts, then go through it again and edit it. It’s much easier to clean up a text than writing it for the first time.

It may help to drink a coffee or a glass of wine, and throw your ideas on a piece of paper. There’s a great phrase for this: ”Write drunk, edit sober.”

When you’re looking at refined documents that have been edited many times, it may feel like you can’t possibly write something that good. Just remember, these documents start with bad drafts, and editing makes them better.

Story from Etsy

I often help my direct reports with editing, sometimes even in a one-on-one meeting.

For example, if one of my team members is writing a document about top tips for using data flow, the engineer on my team and I will start by brainstorming a bullet pointed list about the topics the document should cover. We can get to a clear outline in about 30 minutes, and they’ll fill it in afterwards.

I do the editing when they’re done. We collaborate on the diagrams we want to add.

This makes writing easier for them compared to asking them for a fully formed first draft. These tasks are intimidating for most people.

How do you teach your team about the importance of writing and help them improve?

Define the different documents

Make sure they are clear about the types of documents you often use. In software engineering, these tend to be documents like project plans, RFCs, proposals, etc.

Provide templates

Provide them with templates for each type of document. A template can be just one page with the different sections and a description of what each section should contain.

It’s a lot to ask from your team to write a document without you giving them any guidance about the expectations. Providing them a template that they can follow goes a long way.

Provide mentoring

You can mentor developers the first few times they write documents. You can start by co-writing. Take a few sections to write yourself; they take a few sections to write too, and then the two of you collaborate.

Make it clear: Writing is real work

Make sure your team members realize that writing is real work. Track writing project plans, tickets, and writing external blog posts alongside coding tasks. Putting effort into writing good documents takes time, and it’s just as important as writing clean code.

Story from Etsy

We have a rule that everyone writes a ticket in our project management software about what they’re going to do each day. Software engineers tend to feel like writing shouldn’t be any more than a side project. They believe their job is writing code, so writing documents isn’t work.

I’m trying to combat that stigma by leading by example. Whenever I’m writing something, I’ll mention it in our stand-up meetings. For example, “Today I’ll focus on reviewing this platform team’s proposal to rewrite our system in Java.”

The same goes for writing documentation. If you don’t make time for it, you won’t have good documentation. Make sure the documentation is written and edited well; otherwise, it won’t be helpful in knowledge sharing.

This is important work, so make sure everyone takes it seriously.

Bonus advice about the importance of writing in management

It’s both fulfilling and helpful in career development to write publicly.

You put in a lot of work, build great products, and you may end up without anything telling that story. You may have a bullet point or a summary on LinkedIn, but publishing a blog post or a tutorial is far more fulfilling; it tells your story better, and it can stick around in the long run.

I wrote a blog post when I worked at the New York Times about eight years ago, and people still reach out to me about it. It was a side project, but I put in the extra work to write it up well and create visuals to go with it. It’s one of the coolest things I’ve done in my career.

I encourage everyone to try it for themselves.

About Erica Greene

Erica is currently a Senior Engineering Manager at Etsy, and she lives in New York.

Her background as a software engineer is in machine learning, and her team is focusing on machine learning as well. They build the systems that power Etsy’s on-site advertising product.