Teach, Don't Tell (2013)

When I come across bad documentation (which is often), by far the most common problem I find is that the information I needed just plain isn't present.

Articles like this one really aren't helping. If you wrote a piece of software I'm using that doesn't make you my teacher. It makes you someone offering a contract, and what I need to know is what that contract says.

The first duty of your documentation is to be complete and correct. Unless you've got that sorted, no amount of "putting yourself in the student's place" is going to give adequate results.

The flip side of this is: seek documentation, not people.

I spend a lot of time writing documentation. I think it is well written. Many employees do as well. However, some people come to me with questions already answered by the documentation. They aren't interested learning anything, they only want to make their problem into my problem, or they want me to do their job for them. I'm happy to take extra time to guide new employees through something or discuss edge-cases, but with all my day to day tasks, I am simply not given time to spend with senior employees on things answered by the docs.

> The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.

I would like to understand how this would fly for any other domain.

For instance if I buy skillet pan at a home center I generally get 3 lines of advice on how to clean it, and am supposed to then spend perhaps 6 months of trial and error and go through dozens hours or youtube and litterature to become an decent user.

If I buy a car there will be a 400 page user manual, yet no indication on how to replace the rear axle, or how to realign the wheels, or anything that would qualify me as an expert.

If I buy a violin there will be absolutely no instruction whatsoever and I might spend a lifetime to become an expert at it.

Documentation in the real world is usually third party, targeted at a very specific need of a specific public, and isn't supposed to single-handedly make you an expert at anything. I think this gets lost a lot in how people try to document their work and what they expect from projects maintained by volunteers for instance.

PS: by that token, what I expect from documentation is to be absolutely true and accurate. If it's a tall order, no documentation is fine as long as I can spend my time discovering on my own.

A high minded extremely precise but completely obsolete tutorial is IMHO worse than no tutorial in the first place in that a potentially infinite amount of user time will be lost from it, in balance of the few hours the first users gained from it when it was still relevant.

I have a colleague who prioritizes maintaining control over teaching others. He tries to force a particular perspective, emphasizing the importance of his role while fostering dependency rather than sharing knowledge. This seems driven by a fear of losing his job.

My primary focus is backend development, where I assist developers and solve infrastructure challenges. However, I’m so effective in this role that I often end up boxed into it. I’ve been making an effort to expand into frontend development to broaden my expertise, but this colleague operates in that space and isn't the only one who has made it difficult for others to gain traction.

I agree with another commenter that this doesn't tell the entire story, but it tells almost all of it. Nowadays, I discover some new piece of software, visit the Documentation section of its website, and the first thing I see is `How to build SuperMung on the Whizzbang 47 using Mark Williams C'. I have no idea what SuperMung is for, how to use it, what errors I might make, and how to install it on Debian. Similarly, I go to the website for a new programming language, see some examples that give me little insight into what it is for, and find not even an incomplete language specification.

Proper documentation leads me by the hand, starting on what the software is for, what platforms it runs on, some examples of its use (including examples that show how it is useful for solving real-life problems), a thorough tutorial on how to use it, and finally a complete and properly indexed/searchable reference.

Back in the 1980s, I got myself in trouble: I promised a 100-page manual for a software system I had written, and I decided to do it in the then-new TeX. But this was before The TeXBook was published. So I learned TeX by reading the literate source for the code. The manual was duly ready on time, and served the literally thousands of students who relied on it for the next few years.

But when I finally got a copy of The TeXBook, I was astonished by how little I had actually known about using TeX. I had presumably been mostly using it to answer questions such as “why doesn't this work?”, and a lot of the overall principles had simply not been apparent to me. Once I had learned TeX properly, I learned a great deal about how it all worked by going back and reading the literate source. Knuth is a brilliant (if highly idiosyncratic) programmer.

My point here is to emphasize that when someone releases software, their job is not done unless people can learn to use it. That doesn't just mean completeness and accuracy, but a through-line, apparent to the reader, from learning what it does all the way to mastering it, along with the kind of reference information needed when using it.

I have the opposite opinion. Most often, I'm looking for documentation that gets to the point. Just give me a straight answer so I can minimize time I spend reading docs and maximize time I spend using the thing. Tutorials tend to be annoying to read because there's a lot of information unrelated to the topic (setup, advice for beginner programmers) and important information that is missing because the tutorial inevitably chooses one use case and ignores the others.

If I had to pick, I'd rather a dev tell instead of teach. Other people will inevitably write their "how to do x in y" medium articles anyway. These days you can even get an LLM to write it for you, if there's docs that "tell".

I love good docs like everybody else here. But I also have to admit that my own documentation is sub-par. For example the various internal git repos I own and share, do not provided up to date documentation on how to build, deploy etc. Things are moving fast and updating the docs ends up taking the back seat.

However, I have started using AI to update the README.md lately, and it does a really good job. I review what it creates/updates based on my changes and if looks correct, I check it in. This allows me to focus on stuff the AI cannot do. Yet.

If an open source project has great docs, it will attract people for whom the project would be useless without great docs. That doesn't guarantee it will attract more contributors, or encourage people to get involved, or ensure that the maintainer will be happier and more successful over time. It just means they attract more consumers who feel entitled to the maintainer's labour and attention.

More so, "great docs" tends to mean "docs that tell me exactly how to solve my problem so I don't have to think about it". Otherwise the docs are "bad". It's all about Hickey-esque subjective "ease" and not objective simplicity and excellence. This is why "read the source code" or "read the tests" is treated as a sin here: they demand some kind of interpretative effort from the reader, some sense of adventure, and so on. The author also assumes a priori that the source code will be bad and the tests will be unreadable... but at the same time expects that you will write stellar docs and handhold everyone with the patience of a saint.

If everyone demanded this, there'd be no real open source. Forks would never get picked up, ideas wouldn't get recycled unless they were actively taught, and there wouldn't be an ecosystem.

What this person is basically saying is that it isn't enough to release your code, no, you must in fact write a book and then start a school, and spend all your time patiently dealing with students.

If that's your ambition, great, but the idea that this is the baseline you need to do is absurd. Personally I dislike the kind of student described here very much. I didn't get along with them in college either.

Btw, you can try writing all the docs you want, but nobody will ever tell you why your docs are bad and what would make them better. Just doesn't happen.

Signals And Threads (a Jane Street podcast) had an interesting discussion about documentation [0]. There was also an interesting reference to literate documentation (I think similar to Jupyter notebooks but as documentation).

[0] https://signalsandthreads.com/writing-technically/

This article is primarily about making documentation more effective for learning, not about replacing technical completeness. The best approach combines both perspectives rather than treating them as an either/or proposition.

99% of interactions with documentation can be solved by showing 10 lines of code related to a specific use case. Optimise for someone with a problem to solve who doesn’t necessarily want an intimate, long-term philosophical relationship with you. Once you have them hooked, make it easy for them to configure edge cases and discover wider and deeper functionality (hyperlink generously!), and when they know the bones of your system you can stitch together more of a narrative and talk about architecture and design patterns. But too much documentation is effectively blogging by a maintainer to other would-be maintainers passionate about the subject matter.

Alas, link rot has eaten The Science of Scientific Writing. It was archived here: https://web.archive.org/web/20170614175347/http://www.americ...