Factorio runs on Apple Silicon

Writing docs well: why should a software engineer care?

azhenley
82
35
4d
1
SURFINGCOMPLEXITY.BLOG

Comments

Jensson 4d
> 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.

verdagon 4d
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

socialismisok 4d
There are few skills more important to an engineer than concise, clear technical writing. It enables engineers to scale beyond themselves.
samsquire 4d
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 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.

TheOtherHobbes 4d
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.

jatins 4d
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

zppln 4d
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.

ChrisMarshallNY 4d
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/

oxff 4d
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.

WallabyEV 4d
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....

throwaway0asd 4d
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.
arminiusreturns 4d
Do you want your ops team waking you up at all hours of the night? Keep on giving half-assed docs to them.

It's a leadership and project management failure. What should be done is gates where your shit never goes live unless you have it fully documented.

jiriro 4d
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..