[HN Gopher] Teach, Don't Tell (2013)
___________________________________________________________________
Teach, Don't Tell (2013)
Author : Tomte
Score : 66 points
Date : 2025-03-16 17:55 UTC (5 hours ago)
(HTM) web link (stevelosh.com)
(TXT) w3m dump (stevelosh.com)
| mjw1007 wrote:
| 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.
| fn-mote wrote:
| 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".
| cjfd wrote:
| 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.
| mjw1007 wrote:
| 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.
| AlienRobot wrote:
| 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.
| Swizec wrote:
| 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.
| kkapelon wrote:
| You actually need four https://docs.divio.com/documentation-
| system/
|
| Explanation (why, what)
|
| reference (API spec)
|
| tutorials
|
| How to guides
| Swizec wrote:
| Thanks! Knew I was missing something. I guess in my mind
| tutorials and howtos merged :D
| ranit wrote:
| 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
| Phlebsy wrote:
| 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/
| AlienRobot wrote:
| Making these 3 from static websites generated from docstrings
| is a multi-billion dollar industry called LLMs.
| dharmab wrote:
| A docstring won't contain the necessary context for "why",
| and is something I see coding assistants get consistently
| wrong without human data.
| ChrisMarshallNY wrote:
| 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/
| vo2maxer wrote:
| 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.
| vincent-manis wrote:
| 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.
| apt-apt-apt-apt wrote:
| 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.
| anitil wrote:
| 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/
___________________________________________________________________
(page generated 2025-03-16 23:00 UTC)