
Teach, Don't Tell - stevelosh
http://stevelosh.com/blog/2013/09/teach-dont-tell/
======
cousin_it
The most important thing I want from API documentation is that every method
should have a minimal working code example.

Minimal - the example should be focused on demonstrating how to call that
specific method, with as little other code as possible. That way I don't have
to puzzle which parts are essential and which are arbitrary.

Working - if I paste the example code into a separate file and run it, it
should work. Surprisingly many attempts at documentation fail this test.

When we're faced with an unfamiliar problem and an unfamiliar API that can
solve that problem, the quickest way of programming is copy-paste programming.
The documentation should make copy-paste programming as easy as possible.
Understanding comes after imitation.

~~~
roopeshv
I think this is a wonderful class for someone starting out and a good outline
for people who want to get into practice of doing systematic design.
[https://class.coursera.org/programdesign-001/class](https://class.coursera.org/programdesign-001/class)

------
zdw
> "Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the
> time and effort to write some real documentation instead."

I simultaneously agree and disagree with this. Wikis fall into two categorys:

1\. "If I build it, they will come", which is where the developer who doesn't
want to write docs throws one up, and says "hey, all you users, document it on
your own, I don't want to mess with it". Then new versions come out, things
change, the docs are old/incorrect, and people get frustrated, and nobody
end's up using the wiki.

2\. People who actually take time to make it into a great site - these are few
and far between. [http://ipxe.org](http://ipxe.org) is one example of a well
done wiki, but I'm betting that a single person spent a good deal of time
doing the site.

Unfortunately, it appears that 95% of the technical documentation wikis out
there are in group #1, not group #2.

~~~
solistice
But if it's just one person maintaining the wiki, with a few others
contributing, why have a wiki at all instead of a centrally curated guide?

With wiki like systems, you get noise (in the form of people making mistaken
changes, malicious changes, etc.). There's really only two ways you can
guarantee quality, which is either the aforementioned person reversing those
changes (undoubtedly additional work), or enough people checking those edits,
improving or reverting them.

But your small to medium size project isn't going to garner enough people to
have the latter option work well. And if you have a small group of people that
would be willing to do that maintenance work, why not just write some
documentation together with them?

~~~
derefr
What do you call a wiki coupled to a permissions system? That is, a CMS where:

\- every logged-in user is a contributor+editor+publisher and so can just
edit-and-post content _as if_ the system was a wiki,

\- but new users have to be created by some administator, or invited, etc;
there's no "Register" link,

\- and for non-logged-in users, there are no trappings of "wikidom" visible
(e.g. recent changes page, sandbox, any revision of posts other than the
marked-as-last-known-good revision, etc.)

I have a feeling that this is what 90% of documentation projects really want:
something that's a wiki from the inside, and a CMS from the outside. Does this
design have a name?

~~~
emddudley
A wiki. You can customize wiki UIs to act exactly as you're describing, it's
just that nobody changes the defaults.

~~~
derefr
You can customize wikis to make them into MMO games, but then they're not
wikis any more. It would be useful to have a name, I think, for this specific
thing, because then people who want this specific thing could download
software that already provides this specific thing, with no customization
involved.

~~~
saraid216
> You can customize wikis to make them into MMO games, but then they're not
> wikis any more.

That's not necessarily true. I think it'd be interesting to make a religion-
inspired MMO game that's about writing and rewriting a holy text. Use a voting
system to make something sacrosanct and thus harder to make changes to.

------
mathattack
It's a very important topic, but I have to admit the sequencing threw me for a
loop. If every tech documentation that I read started with, "Before you read
this post there are two other things I think you should read first" I think
I'd never have the patience for an answer.

Better to start with, "Here's what is important to know, if you want to
understand more context, read X and Y"

~~~
derefr
I read the sequencing more as "the most important thing to know, is the thing
I didn't write. Read that. If you never make it back here, that's okay, this
is just errata compared to that."

------
7402
"The purpose of technical documentation is ... teach them to be an expert user
of it"

But maybe I don't WANT to be an expert user! Maybe I just want to USE the damn
thing.

It's frustrating when a tool maker thinks that their tool so important that
every user must become an expert on every facet of the tool. How about, "The
purpose of technical documentation is to teach the user whatever is necessary
and sufficient for their particular needs."

I'm a programmer. A few times a year I need to use Photoshop for something
Really Simple. I want documentation that can tell me how to draw a rounded
rectangle with a shaded gradient inside it (or whatever) as quickly as
possible, and tells me as little as possible about anything that doesn't help
do that.

~~~
solistice
Doesn't Stack-anything fill that niche already, along with a multitude of
youtube videos and online tutorials that will walk you through the most common
use cases, especially for software like photoshop?

In case that's an actual question, make a rectangular selection and check the
"rounded corners" box at the top left. Select the gradient tool (You can see
it by clicking the little paintbucked on the left toolbar for a while, it
looks like a gradient). Klick somewhere and drag with the tool selected. And
there's your rounded rectange with a shaded gradient inside.

~~~
ksmiley
> Doesn't Stack-anything fill that niche already?

If you ask, "how do I use [library X] to draw a rounded rectangle?" on Stack
Overflow, they will put your question on hold until you show code that
demonstrates that you tried. This may be difficult for someone who has only
just succeeded in getting the library to compile!

To continue the author's car analogy, Ms. Smith sits in the passenger seat
while you try to drive to grandpa's house. When you fail to reach your
destination and give up, Ms. Smith will tell you what you did wrong. But only
if you made a non-trivial effort. If you ram into the living room while trying
to exit the driveway, you'll only get a disapproving glare.

------
peter_l_downs

        > When you release a new programming language or library into the wild,
        > the initial state of your “users” is going to be blank.
        > The things they need to know when they encounter your library are:
        >
        >   1. What is this thing?
        >   2. Why would I care about this thing?
        >   3. Is it worth the effort to learn this thing?
    

Yes, please! If all libraries / frameworks included this information it would
make everyone's lives so much easier.

------
sirsar

        >Seriously: fuck wikis. They are bad and terrible.
    

Personally I think the Arch Linux wiki does a fairly good job. I refer to it
when setting up _other_ Linux distros.

~~~
yk
Depends, the Arch wiki is great, there is/was the German ubuntuusers.de wiki
and of course Wikipedia, but none of these are designed to teach you the
basics, they are references. By contrast, for tutorials the state of wikis is
quite often tutorial 1-3 is great and the rest just missing.

------
mr_luc
I agree with this part:

> You should have a table of contents that lists each section of the
> “hairball”. And then each section should have its own table of contents that
> lists the sections inside it. A table of contents is a wonderful way to get
> a birds-eye view of what you’re about to read, to prepare your brain for it.
> And of course it’s also handy for navigating around.

I think that in the case of the article, that table of contents could have
been pinned on the left-hand side, instead of using that space for a cool-for-
a-few-seconds effect.

------
abhididdigi
Seriously, I LOVE this post. I see all those kinds of documentations on
Github, and being fairly new to programming Python, I see it extremely
irritating if the documentation is bad and broken. The author just
expressed(with words) what I couldn't.

------
solistice
I feel the authors pain, both from trying to learn frameworks with missing
documentation ("I want to use this function, but there aren't even comments on
it :D"), and having a father who once told me I was retarded for being unable
to convert hex to binary in my head. I was ten.

I agree with the authors main points, but I'm kinda vexed by him trying to
label it documentation. Technically, what he's proposing people to write is
guides, not just documentation. If I write a piece of code, and I explain what
it does, then that's documenting it, and the result is documentation. If I
show you in writing how to use it, I guide you. It's a guide.

So is a guide documentation? You could classify it like that, but i think that
will be a source of confusion. A better term encompassing both guides and
documentation would be supplemental documents, encompassing everything that is
not code. So we get code supplemental documents -guides -documentation
\--comments \--reference manuals

Or something like that. I'm really just being finicky, but I like categorizing
things.

------
singingfish
I wrote a web programming book three years ago (moderately successful, made
back its advance, and got me the career change I was looking for) using a
philosophy that has a very similar approach to this. My approach is:

1\. All code examples must lead to a working program, or can be easily
integrated into a working program. Preferably the program has trivial
functionality. Conceptual material must relate back to a working example.

2\. Avoid applying excessive cognitive load to the readers. Human short term
memory has a capacity of 7±2 items. Your material must be pitched at a level
where there is a maximum of five concepts in play at any one time (five being
the maximum "guaranteed" short term memory for a healthy adult). This is much
easier to acheive with goal 1 as it the approach guides the writer as to which
item needs to be explained next.

From that perspective, unix man pages drive me nuts. Learning to read man
pages is one of the core skills that needs to be developed in order to become
an effective user of unix like systems.

~~~
singingfish
the idea of 'five concepts' is interesting as it's related to the level you're
pitching at. The idea is that you get people up and running with the initial
working code, and if they manage that, then they can follow what you're doing
subsequently, and you can keep a feel of their levels of consolidated
knowledge.

------
fohlin
"You teach them." Well, no. You set up a framework of information and
activities which allows the individual to learn.

It could be beneficial to adopt this view, prominent in education, for
software documentation as well. (The article seems to agree, but it is useful
to have you language reflect the student as the active party.) We could
actually look educational strategies such as constructive alignment [1] here:
define the measurable learning outcomes, and provide activities aligned with
those outcomes.

The tutorial comes to mind as a potentially successful component of
documentation. Executed well, it gives at a glance information, while
simultaneously providing natural entry points for hands on activity. Add more
options for self-assessment and soon you will have a very pedagogically sound
learning instrument.

[1]:
[http://en.wikipedia.org/wiki/Constructive_alignment](http://en.wikipedia.org/wiki/Constructive_alignment)

------
calinet6
Fw: AngularJS team... honestly.

------
swamp40
_Of course, son. The car is in the garage and I laid out a set of wrenches on
the workbench. Take the car apart and look at each piece, then put it back
together. Once you’ve done that I’ll take you to the DMV for your driving
test._

Reminds me of the story of young Walter Chrysler and his Locomobile.

Edit: For those interested, it's a quick one page read, starting at the bottom
paragraph of page 5:
[http://www.chryslergroupllc.com/company/Heritage/Heritage%20...](http://www.chryslergroupllc.com/company/Heritage/Heritage%20Documents/Chrysler%20Heritage%201900/Chrysler%20History%20-%20Walter%20P.%20Chrysler.pdf)

------
6d0debc071
One tip I'd give for writing docs is to get Dragon Naturally Speaking and a
really good microphone. It's saved me countless hours over the last couple of
years (but only because I stopped counting once I reached 500.)

------
twosinxcosx
I actually want to try writing technical docs, but I can't seem to find a
beginner friendly project/framework that I can pick up a small task and work
on it. Do you have any suggestions?

Shall I try approaching people in Mozilla etc where they always have some work
or wait until I find a project that I personally use and lacks some docs so I
can try working on it individually? I would rather have some kind of
mentorship but I do not think people will invest time in a random person over
the internet.

------
RWeaver
I wish I could upvote this a thousand times. It's great documentation, about
documentation.

I wonder if it would be worth encouraging people to put their names on
official documentation that they write. They'll take some pride in it, and get
some benefit in that they're recognized as an expert, and everyone else gets a
whole bunch more well written documentation (hopefully)

------
scoofy
I cannot be the only one that felt the titles of the subsections popping up on
the left side were entirely redundant and very distracting.

~~~
holyjaw
Quite the opposite - I've always wanted to replicate that part of his site.

------
simonsarris
I've tried to adhere to something similar to this for as long as I've written
a library, and one of the great things about writing JavaScript libraries is
that you can execute tutorials with live code execution _inside the
documentation itself._

I wouldn't call it teaching _per se_ , more of a framework for self-learning,
especially for users who learn by example. I'd stick with the older saying _"
Show, Don't Tell,"_ while making sure they can copy what you've shown.

I think this is a simpler rubric: There should be at least two parts to
documentation, API and Introduction pages. The introduction pages start off
with a "First Contact" page and then delve into the myriad topics of the
library (with a "Hairball" table of contents to explore if they please). These
topics that may not all be relevant to a particular user, and ought to be as
independent as possible. Ideally users should not be expected to read many
pages before making sense of any other page.

The API must contain definitions for every method and property, but should
also make clear what the _purpose_ of any particular class is and give a short
explanation of common usage. The API should then link to the introduction so
that common example code can be seen in action. Both the API and the
introduction pages reference each-other constantly.

For example in my library the Panels API page[1] contains several paragraphs
outlining the purpose and common layout options of Panels, as well as
(importantly!) linking to the associated introduction pages[2], where a user
can see running code examples of common Panels, with code they can directly
copy/paste into their own page to achieve identical panel layouts.

The result should be something tightly coupled, with many links back and forth
between introduction pages and the API, but the end result is not an actual
wiki. I can understand the author's hatred of wiki's, because for most
projects setting up a wiki is a lot like shifting responsibility for creating
documentation to nobody. Which means it never gets done. (At for most projects
I've seen and I think the author would agree. I'm sure there are a few great
library wikis out there with nontrivial user-sourced content.)

[1] Panels API page:
[http://gojs.net/beta/api/symbols/Panel.html](http://gojs.net/beta/api/symbols/Panel.html)

[2] Panels "Intro" page:
[http://gojs.net/beta/intro/panels.html](http://gojs.net/beta/intro/panels.html)

Compare these with, say, the Google Maps API page for "Map":
[https://developers.google.com/maps/documentation/javascript/...](https://developers.google.com/maps/documentation/javascript/reference#Map)

Or worse, MVCArray:
[https://developers.google.com/maps/documentation/javascript/...](https://developers.google.com/maps/documentation/javascript/reference#MVCArray)

There's extremely little about what it is, what is expected of it, and common
uses of it.

~~~

If you write a JavaScript library, there is _no excuse_ for not having live
code examples and tutorials tightly coupled as part of the documentation.

~~~
tikhonj
Coincidentally, this is exactly what the School of Haskell[1] tries to do for
Haskell--it lets the reader execute examples right on the page.

[1]: [https://www.fpcomplete.com/school](https://www.fpcomplete.com/school)

With a bit of work, there is no reason to limit this sort of interactivity to
JavaScript.

------
Mithaldu
I wish the text wasn't italic, so it would be easier to read on machines
without antialiasing enabled.

~~~
6d0debc071
It's all text, you can copy paste it into notepad or something. Or just
override the styling on the page.

------
prlin
slightly OT but any suggestions on a better keyboard? I'm doing fine with my
current one but I'd like to know what I'm missing out on.

~~~
holyjaw
From the author: [http://stevelosh.com/blog/2012/10/a-modern-space-
cadet/](http://stevelosh.com/blog/2012/10/a-modern-space-cadet/) (See the
first part about hardware)

~~~
prlin
thanks. didn't see that post.

