Teach, Don't Tell (2013)(stevelosh.com)
stevelosh.com
Teach, Don't Tell (2013)
https://stevelosh.com/blog/2013/09/teach-dont-tell/
76 comments
There are 3 types of documentation:
1. Why/what 2. API spec 3. Tutorial
You need all 3. They are distinct, use different styles, and exist for different purposes and audiences.
1. Why/what 2. API spec 3. Tutorial
You need all 3. They are distinct, use different styles, and exist for different purposes and audiences.
You actually need four https://docs.divio.com/documentation-system/
Explanation (why, what)
reference (API spec)
tutorials
How to guides
Explanation (why, what)
reference (API spec)
tutorials
How to guides
Right! The good old days when the software used to come in a box with several varied width books containing all these Four, and one named Getting Started.
This same set could be easily "transposed" to the contemporary world of web. With all the proper indexing. Why is this "art" "lost" for most of the software :-( ...
BTW, one Excellent incarnation of this documentation art is on the front page right now:
https://news.ycombinator.com/item?id=43381627
This same set could be easily "transposed" to the contemporary world of web. With all the proper indexing. Why is this "art" "lost" for most of the software :-( ...
BTW, one Excellent incarnation of this documentation art is on the front page right now:
https://news.ycombinator.com/item?id=43381627
> Why is this "art" "lost" for most of the software.
Before the internet, the printed book was all you really got. That meant the company distributing the software had to hire technical writers who'd work with the software devs to create all of this, send it to an editor, and ultimately get published.
We no longer live in an era where tech companies hire tech writers. Software documentation lacking is something that can and limp along with jira cases and support services sold rather than trying to put in the upfront effort to fix everything.
Now, for open source software, hate to say it but the docs have always been pretty crap. Certainly some stands out (usually when the business model was around providing services on top of open source software), but nobody is really paying anyone and few people really want to do that sort of free labor.
Before the internet, the printed book was all you really got. That meant the company distributing the software had to hire technical writers who'd work with the software devs to create all of this, send it to an editor, and ultimately get published.
We no longer live in an era where tech companies hire tech writers. Software documentation lacking is something that can and limp along with jira cases and support services sold rather than trying to put in the upfront effort to fix everything.
Now, for open source software, hate to say it but the docs have always been pretty crap. Certainly some stands out (usually when the business model was around providing services on top of open source software), but nobody is really paying anyone and few people really want to do that sort of free labor.
Some places still have very good tech teams, but it still requires working between the teams.
(EX from a company I worked with: https://forums.madcapsoftware.com/viewtopic.php?t=30365)
The writers can't do their work without input from the technical side and the time for that is often not avaliable.
I know I've been punished for taking time to push ideas to tech writers. Not only does it slow me down in other places, it often gets swept away as unnecessary changes because upstream Sr techs disagree.
For example, when I modify ssl configs, I alway reference the files with soft-links. This makes it so you don't need to modify the config files and simplifies keeping old and new certs so you can flip back during the overlap period you should be providing to test. I try to avoid editing production files by hand whenever possible because in my experience it introduces the possibility to create errors.
I rewrote some docs extending alot of areas with example commands showing how to test things, with explanations that fleshed out the previous quick and dirty documentation. I also modified the method from copy and replace certs, edit files, restart service; to copy files, replace or create soft-link, restart service.
Upstream approvers trashed the whole thing because the thought it was unnecessary and disagreed with me about manually editing config files.
The writers can't do their work without input from the technical side and the time for that is often not avaliable.
I know I've been punished for taking time to push ideas to tech writers. Not only does it slow me down in other places, it often gets swept away as unnecessary changes because upstream Sr techs disagree.
For example, when I modify ssl configs, I alway reference the files with soft-links. This makes it so you don't need to modify the config files and simplifies keeping old and new certs so you can flip back during the overlap period you should be providing to test. I try to avoid editing production files by hand whenever possible because in my experience it introduces the possibility to create errors.
I rewrote some docs extending alot of areas with example commands showing how to test things, with explanations that fleshed out the previous quick and dirty documentation. I also modified the method from copy and replace certs, edit files, restart service; to copy files, replace or create soft-link, restart service.
Upstream approvers trashed the whole thing because the thought it was unnecessary and disagreed with me about manually editing config files.
The downside to all that was software releases happened once every year (or longer). Which, was it actually all that bad, but let’s not be completely wooed by the green looking grass on the other side. There were long delays between new features or bug fixes.
Yes, the upside of the contemporary on-line software distribution is clear. No question about this. "The good old days" :-) reference was only about the comprehensive and ordered documentation that often used to come with the physically shipped software medium.
I suspect all many documented projects died because people couldn't figure out how to use them. By natural selection, anything that survived the good old days is either obvious or well documented. The C programming language, for example.
> By natural selection, anything that survived the good old days is either obvious or well documented
Or so much better than the competition that people use it in spite of poor documentation. Many things like that also grow a cottage industry of people making documentation and teaching (see React or Rails).
Or so much better than the competition that people use it in spite of poor documentation. Many things like that also grow a cottage industry of people making documentation and teaching (see React or Rails).
What is the difference between "Tutorials" and "How to guides"?
It is explained well in the video, well worth watching.
Tutorials are teaching a method, like which ends of the pliers you grab. They do not assume a lot of domain knowledge.
HowTos pick the user up where she stands with a concrete problem and walks you through a possible solution of that specific problem. Like how to use pliers to twist a wire just firmly enough to hold two things together.
Tutorials are teaching a method, like which ends of the pliers you grab. They do not assume a lot of domain knowledge.
HowTos pick the user up where she stands with a concrete problem and walks you through a possible solution of that specific problem. Like how to use pliers to twist a wire just firmly enough to hold two things together.
Often referred to, as “recipes.” —Defining the goal, and a specific set of steps, to achieve that singular outcome.
How to calculate the airspeed velocity of an unladen swallow, etc.
How to calculate the airspeed velocity of an unladen swallow, etc.
+1 for recipes
I have provided recipes in my documentation for complex projects, making it a time-saver for both me and my audience.
I like the concept. I will note the same thing I said further down though:
Why don’t they use their proposed system to explain their own system?
It seems like a wasted opportunity. So odd. Or am I missing something?
Why don’t they use their proposed system to explain their own system?
It seems like a wasted opportunity. So odd. Or am I missing something?
Thanks! Knew I was missing something. I guess in my mind tutorials and howtos merged :D
There's another more thorough version from the same author, for what it's worth. Just moved on from that company but the overall points are the same https://diataxis.fr/
Would have been great if they organized this document exactly as they propose. But they don’t? Which is a bit weird to be honest.
But they sort-of do, no? The left hand side bar has the top-level (bold) headers "Home", "Start Here", "Applying Diátaxis", "Understanding Diátaxis" and "Colophon". The middle ones could well be labeled "Tutorial", "Explanation" and "Reference", but that would be very confusing for the reader!
I like to think of it as learning a foreign language. You need a text book, an English to language dictionary, and those tapes that walk you through a conversation.
Making these 3 from static websites generated from docstrings is a multi-billion dollar industry called LLMs.
My biggest peeve, is bad indexing.
The docs are there. The information is there, but finding it, is so difficult, that I have often just said "bugger this for a lark," and written my own implementation.
There's two types of docs: The teaching kind, as the article mentions, and the reference kind, for helping folks that already have a start, to find what they need.
I generally do the second. It can be fairly easily generated from inline headerdoc comments, these days, but we still have the issue of indexing, and I still have my work cut out for me, there.
Here's some stuff I wrote about my approach to documentation: https://littlegreenviper.com/leaving-a-legacy/
The docs are there. The information is there, but finding it, is so difficult, that I have often just said "bugger this for a lark," and written my own implementation.
There's two types of docs: The teaching kind, as the article mentions, and the reference kind, for helping folks that already have a start, to find what they need.
I generally do the second. It can be fairly easily generated from inline headerdoc comments, these days, but we still have the issue of indexing, and I still have my work cut out for me, there.
Here's some stuff I wrote about my approach to documentation: https://littlegreenviper.com/leaving-a-legacy/
Absolutely this! If I have to use a search box to find docs and not the navigation pane you know you're doing something wrong with your docs.
I’m hoping that LLMs may be helpful, here. Sort of like a “documentation concierge” service. Like going to the reference desk in a local library, and asking The Librarian to help you find some information.
I believe so. I am also hoping it can just pull in repositories and tell me more about the code and history relating to it. There is a lot of potential to this. TLDRs are needed for code, LLMs will be an excellent replacement.
I actually like re-writing documentation, but if I can not reorganize the documentation too I am discouraged from re-writing. I believe a lot of contextual information is lost when people use confluence as a dumping ground and don't plan the structure of the documents.
I've emotionally moved to git for documentation, but I can not get people to follow or transition to better documentation methods once someone is emotionally tied to tribal knowledge and communication.
I've emotionally moved to git for documentation, but I can not get people to follow or transition to better documentation methods once someone is emotionally tied to tribal knowledge and communication.
I can confirm this from the producer side.
The documentation is often neglected.
I got fed up with the Word docx (with code examples) we sent out to our customers and replaced it with a hosted Docusaurus markdown documentation.
It is a lot of work to transfer the knowledge to a the new place. It is a lot of work to keep the documentation up-to-date. It is also a lot of work to formulate things in a widely understandable way with screenshots and good examples.
Still I would do the same refactoring again. While the documentation is still not perfect, our customers now comment that it truly helps them to get going fast with our product. A search function is also very helpful.
Our QA team does follow the integration instructions in the documentation when a major change is released (so "putting somebody in the student's place" does work for us). It of course takes time.
I got fed up with the Word docx (with code examples) we sent out to our customers and replaced it with a hosted Docusaurus markdown documentation.
It is a lot of work to transfer the knowledge to a the new place. It is a lot of work to keep the documentation up-to-date. It is also a lot of work to formulate things in a widely understandable way with screenshots and good examples.
Still I would do the same refactoring again. While the documentation is still not perfect, our customers now comment that it truly helps them to get going fast with our product. A search function is also very helpful.
Our QA team does follow the integration instructions in the documentation when a major change is released (so "putting somebody in the student's place" does work for us). It of course takes time.
I agree that this article isn't doing something for me.
It barely covers the important points of what _should_ be done, and spends a lot of time lampooning bad approaches to documentation.
I also found the metaphor of "the black triangle" obscured the main point of that part of the argument, which to me was "have some foolproof basic starter setup to get a user up and running quickly".
It barely covers the important points of what _should_ be done, and spends a lot of time lampooning bad approaches to documentation.
I also found the metaphor of "the black triangle" obscured the main point of that part of the argument, which to me was "have some foolproof basic starter setup to get a user up and running quickly".
> The first duty of your documentation is to be complete and correct.
It is probably unrealistic to expect documentation to be complete as it is not clear where the border on inclusiveness goes.
Take eg. AWSs node packages. Here they spend words recommending using async / await which IMHO is firmly outside the scope of library docs.
I am curious on what you feel is missing? is it elements concrete to the piece of software you use, or is it pieces that can be deemed expected knowledge from a professional software developer.
It is probably unrealistic to expect documentation to be complete as it is not clear where the border on inclusiveness goes.
Take eg. AWSs node packages. Here they spend words recommending using async / await which IMHO is firmly outside the scope of library docs.
I am curious on what you feel is missing? is it elements concrete to the piece of software you use, or is it pieces that can be deemed expected knowledge from a professional software developer.
The former.
Yes, using the analogy used in the article, programmers are not the students trying to learn how to drive, they are the professional engineers and mechanics that build and maintain the cars. They don't need teaching, they need technical documentation. They already should possess the know-how to transform such documentation into practical applications.
The "be a teacher" motto is how you end up with "documentation" that is a bunch of examples of how to do various things and then no exhaustive and rigorous technical reference or even none at all. And then good luck scouring blog posts and StackOverflow or ask help on IRC (pray it's not on Discord) in the hellscape that has become Internet search if you want to do anything not in the examples.
The "be a teacher" motto is how you end up with "documentation" that is a bunch of examples of how to do various things and then no exhaustive and rigorous technical reference or even none at all. And then good luck scouring blog posts and StackOverflow or ask help on IRC (pray it's not on Discord) in the hellscape that has become Internet search if you want to do anything not in the examples.
The article is quite a bit smarter (if a bit long) than this comment. "The first duty of your documentation is to be complete and correct". The source code satisfies this demand. It is complete and it truly describes the product in all its details. But now we are stuck in 'act 1' of the article. So maybe we need some more helpful hints. O wait, there is an article called 'Teach, Don't Tell' that provides these helpful hints.
The bad documentation I come across often shows every sign of having taken the advice from this article (and others like it) to heart.
The trouble is that the advice doesn't include ways to make sure your documentation actually covers everything it has to.
What this article says is that you should have « "API documentation" for every user-facing part of your project. »
That commonly leads to "reference" pages which are very little better than the autogenerated documentation the author dismisses. The main problems tend to be that behaviour that isn't controlled by a specific command or function or configuration setting doesn't get documented at all, and that commands with complex behaviour get described using terms that themselves need further definition which isn't provided anywhere.
The trouble is that the advice doesn't include ways to make sure your documentation actually covers everything it has to.
What this article says is that you should have « "API documentation" for every user-facing part of your project. »
That commonly leads to "reference" pages which are very little better than the autogenerated documentation the author dismisses. The main problems tend to be that behaviour that isn't controlled by a specific command or function or configuration setting doesn't get documented at all, and that commands with complex behaviour get described using terms that themselves need further definition which isn't provided anywhere.
My experience is that the main problem with online documentation is that it doesn't include links to separate tutorials, but has plenty of links to more documentation, leading you to wander from page to page without destination trying to find that one page that actually explains what you're trying to do or infer it from fragments of information scattered around the documentation.
For example, in Qt you have a view class, a model class, and a selection model class, and none of their pages tell you how to actually select something programmatically. You have to guess or ask ChatGPT these days.
For example, in Qt you have a view class, a model class, and a selection model class, and none of their pages tell you how to actually select something programmatically. You have to guess or ask ChatGPT these days.
> The source code satisfies this demand.
If it's available...
Also, it's much harder to parse multiple files than one doc. Been there, done that, aplenty. Yes, I can find the answer, but that isn't sufficiently going to make it easier. Plus, if one admits the docs are bad because "the source answers that type of in-depth question", then are the docs not still bad?
If it's available...
Also, it's much harder to parse multiple files than one doc. Been there, done that, aplenty. Yes, I can find the answer, but that isn't sufficiently going to make it easier. Plus, if one admits the docs are bad because "the source answers that type of in-depth question", then are the docs not still bad?
Sure, if the docs are bad, the docs are bad ;-). Jokes aside, though, I think the nice thing that this article does is pointing out various common ways in which the docs can be bad. My 'favorite' one is having docstrings for documentation. They take quite a bit of time to write, clutter the code with helpful information like 'the method get_heigth, gets the height' and if they are the only thing that is shipped as information use users severely lacking.
Another thing to note is that what this article lists as good docs actually cost a lot of time to create. Perhaps this is why people settle for the less than helpful alternatives. I think, though, that it is better to provide a subset of the good docs rather than useless docs that just annoy people.
Another thing to note is that what this article lists as good docs actually cost a lot of time to create. Perhaps this is why people settle for the less than helpful alternatives. I think, though, that it is better to provide a subset of the good docs rather than useless docs that just annoy people.
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.
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.
> However, some people come to me with questions already answered by the documentation. They aren't interested learning anything,
Not entirely a counter, but i think it's worth remembering that because documentation is difficult - a lot of people have been trained to ignore documentation by way of documentation not being the answer in far too many cases.
I'm sure there are many people whose behavior is driven by the reasons you give, though.
Not entirely a counter, but i think it's worth remembering that because documentation is difficult - a lot of people have been trained to ignore documentation by way of documentation not being the answer in far too many cases.
I'm sure there are many people whose behavior is driven by the reasons you give, though.
The problem is that often people come to you and just want a solution to their particular problem. Then you explain but forget or leave out some details because you assume they know those. If you're too verbose, they might just have read the documentation.
In fact the best thing to do is to point them to the correct paragraph in the correct document.
In fact the best thing to do is to point them to the correct paragraph in the correct document.
It is unprofessional for someone to just assume their co-worker has done a bad job, no?
Not if every other coworker they've ever had has done a bad job at this particular thing, no. That's just rational
I think documentation feels like a bit of a sink, as written documentation starts degrading (in terms of being up-to-date) as soon as it gets published, and it gets extremely frustrating going through docs and not feeling like you can "trust" what you're reading
It depends on whether you have better people skills or better reading comprehension. I use whatever source gets me the answer fastest as I am skilled in both. That's not true for everyone, but being able to use a decision tree where you have both options is a big part of being a 10x programmer IMHO.
Is your PM/BA/Coworker so overwhelmed they can't think straight (Mind your P's & Q's)? -> Go look at the docs.
Can you politely insert yourself into a conversation with a coworker given their bandwidth and their ability to understand functional and technical requirements and quickly explain what is required? -> Schedule a short meeting.
Is your PM/BA/Coworker so overwhelmed they can't think straight (Mind your P's & Q's)? -> Go look at the docs.
Can you politely insert yourself into a conversation with a coworker given their bandwidth and their ability to understand functional and technical requirements and quickly explain what is required? -> Schedule a short meeting.
It can be hard to find the thing you're looking for in documentation, especially if you're not too familiar with the piece of software you are currently looking at. Saving your coworkers a couple of hours by spending ten minutes of your time can be a good trade - even though it's annoying for you.
As I've said, the docs work for many people. Even in a situation where something is hard for someone, I disagree. It reinforces learned helplessness. Yes, work sometimes will be hard, but things get easier as you gain experience. To be fair to myself, the company cares if I achieve my goals and, importantly, does not give me extra time or extra credit to achieve other people's goals. Even with this in mind, as I've already said, I understand the importance of going the extra mile in some cases (to my own detriment). If another employee does not have the initiative or wherewithal to go through the normal channels and is only interested in skipping the line, this is not a good trade for me or our company.
If people are still coming up with you for questions that the docs answer, then the docs are not discoverable. Nobody is going to sit through hours of docs to find that one small thing they are interested in knowing the answer to _right now_.
LLMs can solve this to some extend now tbh.
LLMs can solve this to some extend now tbh.
As I said, people doing this aren't interested in looking for an answer. They're interested in making their problem someone else's problem. An AI agent doesn't solve this.
Insofar as "the problem" is sifting through pages and pages of documentation to find the relevant information for an answer, I think that current-day LLMs are actually quite capable at this.
Before needing an LLM for it, they might want to ensure their doc system is using a search system that actually works. There's too many doc-focused templates / apps that have the worst search possible.
They expect you to teach them in a way that's immediately understandable to them, and if they don't get it immediately, it's your fault. They get offended if you tell them a single thing they already know, but also blame you if you fail to tell them anything that they don't already know but need to. They'll complain about a lack of documentation, and then won't read it when it's there, and if they do, they complain that it's too hard to understand.
I've had a coworker ask me how to do something in a general way, and tell me "please don't tell me 'it depends on the context'. I just want to do my job and go home." Of course, it did depend on the context. Everything does. This is a senior software engineer with 16 years of experience.
I've had a coworker ask me how to do something in a general way, and tell me "please don't tell me 'it depends on the context'. I just want to do my job and go home." Of course, it did depend on the context. Everything does. This is a senior software engineer with 16 years of experience.
Similarly: monitoring dashboards
You can find the exporters like we did, scrape away. Stop trying to get me to look at it with you
You can find the exporters like we did, scrape away. Stop trying to get me to look at it with you
> 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 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.
My domain is mechanical engineering. In my discipline, the Parker O-Ring catalog or the Omega Sensors catalog are basically textbooks which teach you how to specify and select seals and sensors. They create experts, and in the process, create sales and users.
The really outstanding trick of these catalogs is they also work as shortcuts. You can go to a table and pick an O-ring with very little expertise, and it will tell you the groove size, corner radius, etc.
In short, when you're documenting tools or engineering components, and your audience is tool users, teaching is a highly effective approach.
The really outstanding trick of these catalogs is they also work as shortcuts. You can go to a table and pick an O-ring with very little expertise, and it will tell you the groove size, corner radius, etc.
In short, when you're documenting tools or engineering components, and your audience is tool users, teaching is a highly effective approach.
My first job out of college was mostly designing hardware and writing product user manuals for our industrial I/O interfaces. I agree: those massive Omega catalogs were like textbooks to me. I learned an enormous amount about sensors and how to interface to them and that knowledge is still useful decades later.
One thing missing in this discussion is that the audience is important. Omega Sensor catalogs are great for design engineers. OTOH, you can find a lot of the same products in a McMaster-Carr catalog, but their focus is on the buyer and they are well optimized to sell to that person.
One thing missing in this discussion is that the audience is important. Omega Sensor catalogs are great for design engineers. OTOH, you can find a lot of the same products in a McMaster-Carr catalog, but their focus is on the buyer and they are well optimized to sell to that person.
Hm. I'm trying to see how these examples here match what the article focus is.
The article focus is the shape and structure of useful documentation, provided by the project or by third parties, that, the article doesn't say.
Now. Skillets are a commodity. Training material is completely detached from the product, except maybe for cleaning and maintenance. For motor vehicles, driving instruction is detached from the product. The vehicle manual focuses on how to use _this_ car (in contrast to how to use _a_ car, e.g. in traffic). And violin expertise needs a personal trainer.
And likewise, for some programming languages, for example a C compiler, the user manual just teaches how to configure _this_ compiler. It won't teach you C. You buy separate books for C.
But for a new language? a new paradigm?
Let's look at an apples to apples comparison, what would be real-world products of comparable complexity? Advanced Games could be an example. Physical Games that is, like Settlers of Catan.
And of course these come with documentation, because of course they'll desperately fail if the documentation isn't helpful.
We could argue if the presentation of how to get to useful documentation fits today's attention span, I think both the article and the linked resources are very chatty, but the contents is worth reading if you want your technical software product to be successful, imnsho.
The article focus is the shape and structure of useful documentation, provided by the project or by third parties, that, the article doesn't say.
Now. Skillets are a commodity. Training material is completely detached from the product, except maybe for cleaning and maintenance. For motor vehicles, driving instruction is detached from the product. The vehicle manual focuses on how to use _this_ car (in contrast to how to use _a_ car, e.g. in traffic). And violin expertise needs a personal trainer.
And likewise, for some programming languages, for example a C compiler, the user manual just teaches how to configure _this_ compiler. It won't teach you C. You buy separate books for C.
But for a new language? a new paradigm?
Let's look at an apples to apples comparison, what would be real-world products of comparable complexity? Advanced Games could be an example. Physical Games that is, like Settlers of Catan.
And of course these come with documentation, because of course they'll desperately fail if the documentation isn't helpful.
We could argue if the presentation of how to get to useful documentation fits today's attention span, I think both the article and the linked resources are very chatty, but the contents is worth reading if you want your technical software product to be successful, imnsho.
The article felt off to me, and trying to pinpoint why led me back to the core premise of it.
On the examples given, we're talking about building tools. The point of a new library is to integrate into projects, understand its model, adjust and maintain it (deal with the requirements, dependencies, upgrade cycle etc), so to me getting taught how to use it is only a small part of the story, and could be potentially irrelevant.
I've used brand new libraries that have absolutely no documentation and it was fine for me and the team.
What the article really focuses on is perhaps more akin to quick onboarding and marketing.
> what would be real-world products of comparable complexity?
A new car will be the same level of complexity. You see it as different if you focus on the simplest part of it (going from A to B), but even for driving a new car will effectively have a learning curve, he tires don't grip the same, the engine requires a different driving style, the length and volume might require adjustement as well. And that's only the tip of the iceberg, as you'll need to understand how it's wired, how the panels are assembled and what standards are used for the parts to maintain or adjust it to your needs. You'll need to dig deeper if you're planning on running it on tracks or races.
Settlers of Catan comes with a booklet because the rules are the game, and the whole point is to bind the players to the rules. That's generally not the case for building tools (except for DRM or license management?), surely not for a new language.
On the examples given, we're talking about building tools. The point of a new library is to integrate into projects, understand its model, adjust and maintain it (deal with the requirements, dependencies, upgrade cycle etc), so to me getting taught how to use it is only a small part of the story, and could be potentially irrelevant.
I've used brand new libraries that have absolutely no documentation and it was fine for me and the team.
What the article really focuses on is perhaps more akin to quick onboarding and marketing.
> what would be real-world products of comparable complexity?
A new car will be the same level of complexity. You see it as different if you focus on the simplest part of it (going from A to B), but even for driving a new car will effectively have a learning curve, he tires don't grip the same, the engine requires a different driving style, the length and volume might require adjustement as well. And that's only the tip of the iceberg, as you'll need to understand how it's wired, how the panels are assembled and what standards are used for the parts to maintain or adjust it to your needs. You'll need to dig deeper if you're planning on running it on tracks or races.
Settlers of Catan comes with a booklet because the rules are the game, and the whole point is to bind the players to the rules. That's generally not the case for building tools (except for DRM or license management?), surely not for a new language.
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.
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.
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".
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.
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.
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/
[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.
https://diataxis.fr/ is newer/more fleshed out
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...
I know the thread is about good docs, but the title caught my eye. I have been trying to teach my coworkers new tools and techniques for some time. Instead of telling them. It is very very hard. Not everybody is open to being taught. People get married to old ways of doing things and are very very resistant to change.
Good docs are rare like unicorns with a glowing horn.
It doesn't seem to move the needle like a shipped feature does, requires guessing other peoples' perspectives, involves devoted time and effort (that could, you know, be spent on actually useful things) and the effects of not doing it are invisible (but real: user rage, frustration and wasted time).
Only when the importance of good docs is understood will any effort be invested into it. It should be important if the goal is to have more people using something.
It doesn't seem to move the needle like a shipped feature does, requires guessing other peoples' perspectives, involves devoted time and effort (that could, you know, be spent on actually useful things) and the effects of not doing it are invisible (but real: user rage, frustration and wasted time).
Only when the importance of good docs is understood will any effort be invested into it. It should be important if the goal is to have more people using something.
Here’s a working link to explain the black triangle:
https://rampantgames.com/blog/?p=7745
https://rampantgames.com/blog/?p=7745
The best teacher, at least for software developers, is strict automation that yells at you when you are in violation and guides you in moments of confusion. This is how I first learned to write software as a self taught developer many years ago, using a tool called JSLint. Back in the day it came with a warning: JSLint may hurt your feelings.
this is an awesome article, I really enjoyed reading it.
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.