Writing docs well: why should a software engineer care? | Hacker News Reader

Writing docs well: why should a software engineer care?

surfingcomplexity.blog

109 pointsazhenley44 comments

Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it.

One thing there isn't enough of is task-driven documentation. Typically there's a getting started guide and a reference manual, with a huge gap between the two.

The getting started project is usually at the hello world level - ok as far it goes, which is not far.

The ref manual typically has a list of all moving parts but often lacks a list of concepts and terminology. So you look up $thing and have no idea how it fits into what you're attempting to do.

A series of mid-level task-based examples ("How do I...") for the most common use cases goes a long way to bridging that gap.

Also list any platform specific quirks. (Not just "To install this use homebrew $name for MacOS and apt-get $name for Ubuntu.")

And run a forum where people ask questions. Collect the most common questions into a literal FAQ and/or include them in examples/reference.

Never say "That's in the manual." Especially not when the manual is 1000 pages long and gives a two sentence description of every feature with no use cases.

I do despise how little there is of examples in most of the docs. Go had a right idea of integrating example code into tests so not only there is one way to add example code, it is also guaranteed to be runnable.

It also have side effect of forcing developer to use their own interface they gave to users so they might notice it is shit before people start to complain (or leave defeated and search for different lib)

There's a framework to do this in most major languages. I think python started this with TestDoc.

this makes sense I’m guessing this is why I love go and rust so much. it’s like I have the confidence to just figure things out when I get stuck cause of the docs it has

TDD in theory sounds great. What I've seen is thousands and thousands of tests, inconsistently written by dozens of different developers over the years. Testing silly little trivial things that makes the CI pipeline 10+ minutes. A least if you have lots of obsolete difficult to read docs you can easily ignore them, tests however are particularly toxic as it makes refactoring and cleanup very difficult.

> tests however are particularly toxic as it makes refactoring and cleanup very difficult.

Properly written tests check the interface contract, and thus are very friendly watchdog that will warn you as soon as you got out the right path.

Tests that check the implementation details, instead, are hardly ever justifiable.

>Whether it's FOSS or corporate, people won't use your stuff if it's not documented properly. At best they'll use it reluctantly and complain about it.

Maybe FOSS, but there is plenty of corporate SaaS and desktop apps that have basically zero documentation and you are told to contact the "support team" if you can't figure something out.

I think that's the type of software I'd at best use reluctantly and complain about.

Well this is usually what people do. It usually is some company that has a dated or not great app, but has sector capture because they were first or were wise enough to spend on sales and marketing. After that, bigger (non-tech) businesses and governments, just "stick with what works" no matter the aggravation.

The tips at the end of the article are pretty solid. I'll add some more that helped my writing immensely:

* Use bold text once or twice per section to break up the monotony and draw the reader's eye to where you want it.

* Shorten! Cut away anything optional to the reader understanding your main point, and move it to footnotes, sidenotes, or a linked document/page.

* Have someone read your first draft. If they ask a question, don't answer it directly! Update your draft instead.

* Use lists religiously! Walls of text tend to repel attention.

My favorite article [0] happened to use all these tips, if anyone wants to see an example. Happy writing!

[0] https://verdagon.dev/blog/higher-raii-7drl

> Use bold text

Really? Why not just . . .

> Shorten

And as an atheist, I can't stress the next one enough. Listicles are not ideacles, or somesuchacle. Lists show a lack of pedagogical thought.

> Use lists religiously!

> Really? Why not just . . .

> > Shorten

By being too terse you risk avoiding some important aspect for documentation, preventing someone from understanding it.

It's a balancing act.

You're being cute, but losing meaning. Do you support using lists, or do you object to them?

About shortening: highly recommend glancing over "On Writing Well" by Zinsser.

If you only have 30s, just look at this page from this book:

https://scholarsandrogues.files.wordpress.com/2015/05/zinsse...

Stephen King has a similar few pages in his book On Writing. I really really love the short sentences + short paragraph style. One of the author that excels at that is Bukowski.

There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.

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.

Good writing is clearly useful and quite often mentioned. But good reading is very rarely talked about. I think it is even more important.

Too many people cannot maintain attention for more than a few seconds while reading. Or they read "what they want to read" instead of the actual text. Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list.

I tend to write concise documentation, but people always loose some important details that way. So I am now purposefully adding more text than strictly required to be sure important points are really understood.

Like a good teacher repeats at least 3 times the same matter, with a slightly different angle

This reminds me of an old Spolsky blog post on writing specs: [0]

  > Programmers often try to write specs which look like dense academic
  > papers. They think that a "correct" spec needs to be "technically"
  > correct and then they are off the hook.
  >
  > The mistake is that when you write a spec, in addition to being
  > correct, it has to be understandable, which, in programming terms,
  > means that it needs to be written so that the human brain can
  > "compile" it.

[0] https://www.joelonsoftware.com/2000/10/15/painless-functiona...

I think everyone is capable of reading well-written text or code. The problem comes when it’s not well written, in which case you’re in the real of reverse engineering. And most people are bad at RE.

> Like I write a "list of things" and they read it like "a set of things", loosing the meaningful ordering of a list.

That's on you. A lot of code use list instead of set purely because set is rarely a basic primitive language offers.

If I see method returning list of users I'm just gonna assume it is unordered, and it usually is unordered.

If you return list that's ordered and that matters for some reason, the docs should say it is ordered and by which key.

If the method is called RunTasks(list) and documentation is "runs a list of tasks" it is perfectly fine to assume it means "runs list of tasks in order" but it is also perfectly fine to assume "runs all of the tasks in parallel".

3 sentences per paragraph if long-ish, can go 5 if shorter and the rhythm is present in the cadence of language.

Basically until you practice clarity, word choice, and active attention to writing (no spell check, no assists), communicating anything of complexity becomes a planning exercise. How much will it take to convey this information in text? Would a picture work better? A graph to support?

I've made a nice living "translating" from Subject Matter Expert (A/C/E, SaaS, Wall St) into business language for RFPs. 9 times out of 10 a person can talk out a story to me just fine - meanwhile they've stalled writing anything for 3 days past the deadline so it's just making my life more difficult. It's obvious people hate writing in the business realm.

Why? Because once it's written down there's a paper trail and accountability. That scares people who want to use language in shady ways. Hence the phone call after your email to talk about what you just mentioned but not by using the Reply button. Sooooooo predictable....

> Why? Because once it's written down there's a paper trail and accountability.

This. It’s the hard part of getting people to commit to operational plans on the business side as well.

I implement algorithms from descriptions. It's so important that other developers can explain code and be capable of implementing the same thing.

There's usually a critical insight that allows an algorithm to be understandable.

Wikipedia descriptions for btrees, multiversion concurrency control and tries are almost enough to implement them.

I don't like it when developers say the code is the documentation. I don't want to read your code to understand how you implemented the solution to the problem. I would rather read a plain explanation of what you're trying to do and what mental model you used to implement it.

A thing that I started doing at previous $work was accompanying projects with an FAQ doc that'd try to answer potential product/support questions. These would be non-technical docs, that grow over time .

And any time I got pinged in Slack I'd try to find the answer in that doc and link to relevant section as response.

While I found that most people would not read through the entire doc when it is written or the first time it is shared for comments (can't blame them, attention spans are rare these days), they did however start referring to the the doc first after a couple of times of getting the doc link in response.

Recently I read a tweet[0] that describe text as a liability, just like code. And now I feel all docs should come with an archival/revival date. We need more "canonical references" and less long living design review docs that are often shared around as reference docs.

[0] https://twitter.com/thesephist/status/1592924904911163392

If you document something well people won't have to nag you over it.

One of my first real job assignments was a relatively large C project (client/server architecture) behind a simple CLI. I was given the opportunity to document it relatively well (not just the CLI, but the internal design as well). Ten years later there are multiple GUI clients implemented, some even at other companies. One guy even replaced the client-server UDP protocol (don't ask) with a TCP one. Aside from reviewing pull requests for stuff like that, I don't think I've ever had to explain how any of it actually work aside from pointing them to the docs.

This is something that I've always considered crucial.

However, documentation is a "concrete galosh"[0], so I've learned to reduce the sheer volume of docs, and try to tie them to the code, itself. I write about my approach here[1].

[0] https://littlegreenviper.com/various/concrete-galoshes/

[1] https://littlegreenviper.com/miscellany/leaving-a-legacy/

Most developers I have worked with in the corporate world refuse to put things in writing. I have found the people that cannot write also cannot plan or architect software, which is then predictive of the output quality, process, and speed of delivery. It seems this is a form of executive functioning that when absent limits approaches to known patterns and oral discussions.

There's a saying in the physics world, that you don't understand something unless you can explain it to a barmaid. There's also a traditional belief that you really discover the gaps in your understanding when you try to teach it.

Programming languages are intended to be human readable, so it's not entirely surprising that if you can't explain something to humans, chances are you might not be explaining it very well to the computer either.

Do you want your ops team waking you up at all hours of the night? Keep on giving half-assed docs to them. What should be done is gates where your shit never goes live unless you have it fully documented.

What are some good tools to write and maintain documentation?

I can keep docs for myslef in almost any way;) but docs maintened by a team need something easy to use. Plus on-premise storage because of security and privacy..

As a software engineer, docs are quite low in priority. You should be using a language that can do documentation, like Rust, Haskell or even TS if you must use JS.

If you are stuck with JavaScript you have to be careful since you might just make an API that is way more permissive than what you intended to do, or similarly if you are writing Java and need to consider what happens when concurrency happens etc.

My integration tests are the documentation

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

And testing is nature's way of telling you how sloppy your code is, I suppose? (recursion intended)

Yeah, testing shows you that your code is sloppy, writing is even worse since there is no testing at all, even the worst code is better tested than the best text as long as the programmer ran it once.

> writing is even worse since there is no testing at all

Isn't it possible to get a beta reader? Just someone who will go through your writing and give you feedback?

If you are writing docs, a lot of the time you'll also have coworkers there with you, that you'll be able to float the docs to for a quick look, or maybe other people who are interested in your project, if doing open source, or even a friend.

It is a bit worse than automated testing, but surely better than nothing!

Also, there are apps or sites like this, that help you detect when you have run on sentences or complicated wording: https://hemingwayapp.com/

Those could sometimes be useful.

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

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

For simple packages, I understand.

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.

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

Well, yes, like for code comments, the most important parts are the whys.

You're also forgetting that in some situations the source code itself might be unreadable to the person : either because it's just not available (including the comments), or because the reader doesn't know the programming languages (with assembly programming being a bit of both).

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” – Martin Fowler

I've personally found that to write a good API, you need both code that implements the API and code that uses it, and you also need to write the documentation of that API. The former reveals flaws in the machine interface, and the latter reveals flaws in the human interface, so to speak. For instance, you might find yourself spending a lot of text trying to explain the naming and then realize that the naming is simply bad.

Reply on news.ycombinator.com