0

Writing docs well: why should a software engineer care? – Surfing Complexity

 1 week ago
source link: https://surfingcomplexity.blog/2022/11/24/writing-docs-well-why-should-a-software-engineer-care/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.

Writing docs well: why should a software engineer care?

technical-comm-lecture-02.jpg?w=1024

Recently I gave a guest lecture in a graduate level software engineering course on the value of technical writing for software engineers. This post is a sort of rough transcript of my talk.

technical-comm-lecture-03.jpg?w=1024

I live-sketched my slides as I went.

technical-comm-lecture-04.jpg?w=1024

I talked about three goals of doing doing technical writing.

technical-comm-lecture-05.jpg?w=1024

The first one is about building shared understanding among stakeholders of a document. One of the hardest problems in software engineering is getting multiple people to have a sufficient understanding of some technical aspect, like the actual problem being solved, or a proposed solution. This is ostensibly the only real goal of technical writings.

Shared understanding is related to the idea of common ground that you’ll sometimes hear the safety folks talk about.

technical-comm-lecture-06.jpg?w=1024

If you’re a programmer who works completely alone, then this is a problem you generally don’t have to solve, because there’s only one person involved in the software project.

technical-comm-lecture-07.jpg?w=1024

But as soon as you are working in a team, then you have to address the problem of shared understanding.

technical-comm-lecture-08.jpg?w=1024

When we work on something technical, like software, we develop a much deeper understanding because we’re immersed in it. This can make communication hard when we’re talking to someone who hasn’t been working in the same area and so doesn’t have the same level of technical understanding of that particular bit.

technical-comm-lecture-09.jpg?w=1024

If you’re working only with a small, co-located group (e.g., in a co-located startup), then having a discussion in front of a whiteboard is a very effective mechanism for building shared understanding. In this type of environment, writing effective technical docs is much less important.

technical-comm-lecture-10.jpg?w=1024

The problem with the discuss-in-front-of-the-whiteboard approach is that it doesn’t scale up, and it also doesn’t work for distributed environments.

technical-comm-lecture-11.jpg?w=1024

And this is where technical documents come in.

technical-comm-lecture-12.jpg?w=1024

I like to say that the hardest problem in software engineering is getting the appropriate information into the heads of the people who need to have that information in order to do their work effectively.

technical-comm-lecture-13.jpg?w=1024

In large organizations, a lot of the work is interconnected, which means that some work that somebody else is doing can affect your work. If you’re not aware of that, you can end up working at cross-purposes.

technical-comm-lecture-14.jpg?w=1024

The challenge is that there’s so much potential information that might be useful. Everyone could potentially spend all of their working hours reading docs, and still not read everything that might be relevant.

technical-comm-lecture-15.jpg?w=1024

To write a doc well means to get people to gain sufficient understanding so that you can coordinate work effectively.

technical-comm-lecture-16.jpg?w=1024

The second goal of writing I talked about was using writing to help with your own thinking.

technical-comm-lecture-17.jpg?w=1024

The cartoonist Richard Guindon has a famous quote: “writing is nature’s way of letting you know how sloppy your thinking is.” You might have an impression that you understand something well, but that sense of clarity is often an illusion, and when you go to explicitly capture your understanding in a document, you discover that you didn’t understand things as well as you thought. There’s nowhere to hide in your own document.

technical-comm-lecture-18.jpg?w=1024

When writing technical docs, I always try hard to work explicitly through examples to demonstrate the concepts. This is one of the biggest weaknesses I see in practice in technical docs, that the author has not described a scenario from start to finish. Conceptually, you want your doc to have something like a storyboard that’s used in the film industry, to tell the story. Writing out a complete example will force you to confront the gaps in your understanding.

technical-comm-lecture-19.jpg?w=1024

The third goal is a bit subversive: it’s how to use effective technical writing to have influence in a larger organization when you’re at the bottom of the hierarchy.

technical-comm-lecture-20.jpg?w=1024

If you want influence, you likely have some sort of vision of where you want the broader organization to go, and the challenge is to persuade people of influence to move things closer to your vision.

technical-comm-lecture-21.jpg?w=1024

Because senior leadership, like everyone else in the organization, only has a finite amount of time and attention, their view of reality are shaped by the interactions they do have: which is largely through meetings and documents. Effective technical documents shape the view of reality that leadership has, but only if they’re written well.

If you frame things right, you can make it seem as if your view is reality rather than simply your opinion. But this requires skill.

technical-comm-lecture-22.jpg?w=1024

Software engineers often struggle to write effective docs. And that’s understandable, because writing effective technical docs is very difficult.

technical-comm-lecture-23.jpg?w=1024

Anyone who has set down at a computer to write a doc and has stared at the blinking cursor at an empty doc knows how difficult it can be to just get started.

technical-comm-lecture-24.jpg?w=1024

Even the best-written technical docs aren’t necessarily easy to read.

technical-comm-lecture-25.jpg?w=1024

Poorly written docs are hard to read. However, just because a doc is hard to read, doesn’t mean it’s poorly written!

technical-comm-lecture-26.jpg?w=1024

This talk is about technical writing, but technical reading is also a skill. Often, we can’t understand a paragraph in a technical document without having a good grasp of the surrounding context. But we also can’t understand the context without reading the individual paragraphs, not only of this document, but of other documents as well!

This means we often can’t understand a technical document by reading from beginning to end. We need to move back and forth between working to understand the text itself and working to understand the wider context. This pattern is known as the hermeneutic circle, and it is used in Biblical studies.

technical-comm-lecture-27.jpg?w=1024

Finally, some pieces of advice on how to improve your technical writing.

technical-comm-lecture-28.jpg?w=1024

Know explicitly in advance what your goal is in doing the writing. Writing to improve your own understanding is different from writing to improve someone else’s understanding, or to persuade someone else.

technical-comm-lecture-29.jpg?w=1024

Make sure your technical document has concrete examples. These are the hardest to write, but they are most likely to help achieve your goals in your document.

technical-comm-lecture-30.jpg?w=1024

Get feedback on your drafts from people that you trust. Even the best writers in the world benefit from having good editors.

Loading...

TLA+ is hard to learnDecember 24, 2018In "software"

BitrotJanuary 23, 2022In "software"

Conscription devices, boundary objects, and GDocsDecember 24, 2020In "cognitive-systems-engineering"

Published by Lorin Hochstein

View all posts by Lorin Hochstein

Published November 24, 2022

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK