Writing docs well: why should a software engineer care?

> 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.

Coding is natures way of showing how sloppy your thinking is, not writing natural language text. It is really easy to hide sloppy thinking behind natural language, otherwise there would be a lot of overlap between great writers and great coders, but there doesn't seem to be much correlation there at all. Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing.

> Coders tend to be precise with their language, but most people prefer to read imprecise sentences so you easily gravitate towards imprecise language if you try to practice writing.

Preferring to read imprecise sentences comes down to what the purpose of the written work is, does it not? Clear and precise technical documentation and even research papers are really helpful and can be practiced. If it’s poetry or a level of emotional buildup such as in fiction is needed, then that’s what people will prefer. Context on what is being written matters.

In theory yes, in practice documentation tends to be too sloppy to be useful.

The problem is that writing all the details is equivalent to just providing the source code, so you need to explain less. But then unless what you are working with has very clean abstractions the documentation becomes worthless because it doesn't explain things well enough. So in practice documentation for a codebase is mostly worthless unless the codebase is very cleanly written, which wont be the case unless we are talking about programming languages or similar.

The real documentation people use in codebases is looking at how things are used in other parts of the codebase. Then you have examples and maybe even tests showing how it works, so you start from there and maybe test some things if you need to do things a bit differently.

So when is documentation actually useful? When you provide a library that is intended to be used outside of your codebase, so a person who adds the library to his codebase can understand how to use it without having examples to look at in their code. But this is a very specific case and most software engineers don't have to think about it.

If I'm missing something here please explain why, but I've never found any documentation to be useful, except for libraries from outside your codebase. And even for libraries it is often easier and faster to just read the source code if it is available.

Edit: If you are talking about design documents for services and features then those are useful, yes, but that is usually not what people talk about when they talk about software engineers writing documentation.

I see strong writing skills as a vital part of leveling up to senior, staff and higher level positions.

Even more important now that our world is increasingly async-first / remote-friendly.

As I said, well written documentation is impossible unless the codebase is very clean, and trivial to write if the codebase is clean. For anything else the documentation will either be very sloppy with details, span hundreds of pages making it unwieldy compared to browning code where you have tooling to see references etc.

I have written and reviewed many design documents and held presentations, I understand the value of communication, but that value just isn't there for most codebases since their abstractions are way too leaky for documentation to provide any value. A design document explaining why the service or library was built and the design decisions originally taken is often useful since it provides context, but things lower level than that just isn't useful in most codebases people work in.

> For anything else, you are committing hyperbolic falsehood if you (or others) claim that it is "easier and faster to just read the source code" and "even for libraries", compared to reading examples/well-written documentation.

You need to practice reading code and have empathy for the original programmers so you understand their thinking. The original design documents helps a lot with that, then the general naming schemes and such start to make sense and its smooth sailing just reading the code after that. If the codebase was written without any deliberate design or architecture then you have bigger problems than missing documentation...