732 lines
No EOL
39 KiB
HTML
732 lines
No EOL
39 KiB
HTML
<!DOCTYPE html>
|
|
<html lang='en'><head><meta charset='utf-8' /><meta name='pinterest' content='nopin' /><link href='../../../../static/css/style.css' rel='stylesheet' type='text/css' /><link href='../../../../static/css/print.css' rel='stylesheet' type='text/css' media='print' /><title>Teach, Don't Tell / Steve Losh</title></head><body><header><a id='logo' href='https://stevelosh.com/'>Steve Losh</a><nav><a href='../../../index.html'>Blog</a> - <a href='https://stevelosh.com/projects/'>Projects</a> - <a href='https://stevelosh.com/photography/'>Photography</a> - <a href='https://stevelosh.com/links/'>Links</a> - <a href='https://stevelosh.com/rss.xml'>Feed</a></nav></header><hr class='main-separator' /><main id='page-blog-entry'><article><h1><a href='index.html'>Teach, Don't Tell</a></h1><p class='date'>Posted on September 3rd, 2013.</p><p>This post is about writing technical documentation. More specifically: it's
|
|
about writing documentation for programming languages and libraries.</p>
|
|
|
|
<p>I love reading great documentation. When I have a question and the
|
|
documentations explains the answer almost as if the author has magically
|
|
anticipated my problem, I get a warm, fuzzy feeling inside. I feel a connection
|
|
with the writer that makes me smile.</p>
|
|
|
|
<p>I also love writing documentation. Being able to rewire the neurons in
|
|
someone's brain so that they understand something they didn't understand before
|
|
is extremely satisfying. Seeing (or hearing about) the "click" when a bunch of
|
|
concepts suddenly fall together and make sense never fails to make my day.</p>
|
|
|
|
<p>This post is going to be about what I think good documentation is and how
|
|
I think you should go about writing it. I'm not perfect, so you should take
|
|
everything with a grain of salt, but I hope you'll find it useful and
|
|
thought-provoking even if you don't agree with me about everything.</p>
|
|
|
|
<p>I'd like to say thanks to <a href="http://craigzheng.com/">Craig Zheng</a> and <a href="http://honza.ca/">Honza Pokorny</a> for
|
|
proofreading this.</p>
|
|
|
|
<ol class="table-of-contents"><li><a href="index.html#s1-prior-reading">Prior Reading</a></li><li><a href="index.html#s2-why-do-we-document">Why Do We Document?</a></li><li><a href="index.html#s3-teaching">Teaching</a></li><li><a href="index.html#s4-a-play-in-seven-acts">A Play in Seven Acts</a></li><li><a href="index.html#s5-act-1-read-the-source">Act 1: "Read the Source"</a></li><li><a href="index.html#s6-tools-of-the-trade">Tools of the Trade</a></li><li><a href="index.html#s7-act-2-read-the-tests">Act 2: "Read the Tests"</a></li><li><a href="index.html#s8-how-to-teach">How to Teach</a></li><li><a href="index.html#s9-act-3-literate-programming">Act 3: "Literate Programming"</a></li><li><a href="index.html#s10-the-anatomy-of-good-documentation">The Anatomy of Good Documentation</a></li><li><a href="index.html#s11-first-contact">First Contact</a></li><li><a href="index.html#s12-act-4-read-the-docstrings">Act 4: "Read the Docstrings"</a></li><li><a href="index.html#s13-the-black-triangle">The Black Triangle</a></li><li><a href="index.html#s14-act-5-read-the-api-docs">Act 5: "Read the API Docs"</a></li><li><a href="index.html#s15-the-hairball">The Hairball</a></li><li><a href="index.html#s16-act-6-read-the-wiki">Act 6: "Read the Wiki"</a></li><li><a href="index.html#s17-the-reference">The Reference</a></li><li><a href="index.html#s18-act-7-a-new-hope">Act 7: "A New Hope"</a></li></ol>
|
|
|
|
<h2 id="s1-prior-reading"><a href="index.html#s1-prior-reading">Prior Reading</a></h2>
|
|
|
|
<p>Before you read this post there are two other things I think you should read
|
|
first.</p>
|
|
|
|
<p>The first is Jacob Kaplan-Moss' <a href="http://jacobian.org/writing/great-documentation/">Writing Great Documentation</a> series. He's
|
|
certainly more qualified than I am to write about this stuff, so you should
|
|
check that out if you haven't already. A lot of what I say here is going to
|
|
agree with and build on the ideas he talked about.</p>
|
|
|
|
<p>The other thing you should read is <a href="http://www.americanscientist.org/issues/id.877,y.0,no.,content.true,page.1,css.print/issue.aspx">The Science of Scientific Writing</a> by
|
|
George Gopen and Judith Swan. Don't be put off by the fact that it's written
|
|
for scientists publishing papers in journals. Everything in that article
|
|
applies equally well to programmers writing technical docs. Read the entire
|
|
thing. It's worth it.</p>
|
|
|
|
<h2 id="s2-why-do-we-document"><a href="index.html#s2-why-do-we-document">Why Do We Document?</a></h2>
|
|
|
|
<p>Let's get started. The first thing to nail down is <em>why</em> we're documenting
|
|
a programming language or library in the first place. There are many things you
|
|
might want to accomplish, but I'm going to boil them down into a single
|
|
statement:</p>
|
|
|
|
<p><strong>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.</strong></p>
|
|
|
|
<p>At first glance this probably doesn't seem too controversial or interesting.
|
|
But there's one word in there that makes <em>all</em> the difference, and it frames my
|
|
entire perspective on documentation.</p>
|
|
|
|
<h2 id="s3-teaching"><a href="index.html#s3-teaching">Teaching</a></h2>
|
|
|
|
<p>If you want to take a person who has never played the guitar and turn them into
|
|
a virtuoso guitarist, how can you do that?</p>
|
|
|
|
<p>You <em>teach</em> them.</p>
|
|
|
|
<p>If you want to take a high school student and turn them into a computer
|
|
scientist, how can you do that?</p>
|
|
|
|
<p>You <em>teach</em> them.</p>
|
|
|
|
<p>If you want to take a programmer who has never seen your library before and turn
|
|
them into an expert user of it, how can you do that?</p>
|
|
|
|
<p>You <em>teach</em> them!</p>
|
|
|
|
<p>Guitar lessons are usually taught in person, one-on-one, with a teacher.
|
|
Computer Science is usually taught by professors in classrooms. Programming
|
|
library usage is usually taught by documentation.</p>
|
|
|
|
<p>If the goal of documentation is to turn novices into experts, then <em>the
|
|
documentation must teach</em>. You should think of your documentation as a lesson
|
|
(or series of lessons) because <em>that's what it is</em>.</p>
|
|
|
|
<p>When writing technical documentation you (usually) don't have the advantage of
|
|
having a one-on-one dialog with the learners. This makes it a bit more
|
|
difficult, but not impossible as long as you're careful. Your documentation
|
|
needs to fill the role of both the in-person lessons <em>and</em> the textbook.</p>
|
|
|
|
<p>The rest of this post will be almost entirely about how to apply the
|
|
"documentation is teaching" mindset to writing programming docs.</p>
|
|
|
|
<h2 id="s4-a-play-in-seven-acts"><a href="index.html#s4-a-play-in-seven-acts">A Play in Seven Acts</a></h2>
|
|
|
|
<p>I'm going to break up the content of this post with some venting about <em>bad</em>
|
|
documentation. If you want to skip these little rants, go ahead.</p>
|
|
|
|
<p>Each act in our play has two characters: a teenager and a parent. The teenager
|
|
has just turned sixteen and would like to learn to drive so they can hang out
|
|
with their friends without relying on their parents to drive them everywhere.</p>
|
|
|
|
<p>Each act will demonstrate a caricature of a particularly <em>bad</em> form of
|
|
documentation. I hope these little metaphors will help show why certain forms
|
|
of documentation are ineffective cop-outs and why you should write <em>real</em>
|
|
documentation instead.</p>
|
|
|
|
<h2 id="s5-act-1-read-the-source"><a href="index.html#s5-act-1-read-the-source">Act 1: "Read the Source"</a></h2>
|
|
|
|
<p>Our play starts with a son and father sitting at the breakfast table. The son
|
|
is munching on some cereal before school while the father reads his iPad before
|
|
leaving for work.</p>
|
|
|
|
<p>The son says: "Hey Dad, you said you were going to teach me how to drive after
|
|
school today. Are we still going to do that?"</p>
|
|
|
|
<p>The father, without looking up from his iPad, replies: "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."</p>
|
|
|
|
<p>The son quietly continued eating his cereal.</p>
|
|
|
|
<p>If you use many open source libraries you've undoubtedly encountered some whose
|
|
README says something like "read the source". Every time I see one, I die
|
|
a little bit inside.</p>
|
|
|
|
<p>Source code is <em>not</em> documentation. Can you learn to be a guitarist by simply
|
|
listening to a piece of music intently? Can you become a painter by visiting
|
|
a lot of museums? Of course not!</p>
|
|
|
|
<p>Let me be clear: I'm not trying to say that reading source code isn't a valuable
|
|
thing to do. It is!</p>
|
|
|
|
<p>Looking at other artists' paintings is extremely useful <em>once you know how to
|
|
paint</em>. Learning how the brakes of a car are constructed can save your life,
|
|
<em>once you know how to drive</em>.</p>
|
|
|
|
<p>Once your library's users know how to work with it, reading its source is
|
|
absolutely worth their time. But you can't look at the finished product and
|
|
understand the perspective and ideas that went into it without additional
|
|
guidance. That's a job for documentation.</p>
|
|
|
|
<h2 id="s6-tools-of-the-trade"><a href="index.html#s6-tools-of-the-trade">Tools of the Trade</a></h2>
|
|
|
|
<p>Writing good documentation doesn't take much in the way of tools.</p>
|
|
|
|
<p>For example: you don't need a thesaurus. Don't try to avoid using the same
|
|
words by substituting synonyms. Just talk to your users like you would talk to
|
|
another human being in real life!</p>
|
|
|
|
<p>If you use the same word ten times in a row your readers probably won't even
|
|
notice. But I guarantee they're going to notice if you throw in strange,
|
|
uncommon words for no good reason.</p>
|
|
|
|
<p>There are two tools I <em>will</em> recommend before moving on. The first isn't
|
|
actually a tool, but a skill.</p>
|
|
|
|
<p>To write great documentation, you need to be able to type.</p>
|
|
|
|
<p>When you write docs you'll inevitably write yourself into a corner and realize
|
|
you need to take a new direction. If you don't type quickly, you might be
|
|
hesitant to throw away writing that doesn't really work. You need to learn to
|
|
type well so you don't feel bad throwing away a chunk of a thousand words that
|
|
don't fit.</p>
|
|
|
|
<p>Steve Yegge's article <a href="http://steve-yegge.blogspot.com/2008/09/programmings-dirtiest-little-secret.html">Programming's Dirty Little Secret</a> is
|
|
a great rant on this topic.</p>
|
|
|
|
<p>You should also get yourself a nice keyboard. A good keyboard won't make you
|
|
a good writer (just like a good guitar won't make you a good guitarist), but it
|
|
<em>will</em> make you want to write more just for the sheer joy of using
|
|
a well-designed piece of equipment.</p>
|
|
|
|
<p>I started practicing guitar a lot more after I got a new guitar that was much
|
|
nicer than my old one. If you spend a hundred dollars, get a nice keyboard, and
|
|
end up wanting to write more, it was worth it!</p>
|
|
|
|
<p>Be thankful that a nice keyboard only costs $100 to $300 and not several
|
|
thousand dollars like a nice instrument.</p>
|
|
|
|
<h2 id="s7-act-2-read-the-tests"><a href="index.html#s7-act-2-read-the-tests">Act 2: "Read the Tests"</a></h2>
|
|
|
|
<p>The next scene opens with a mother picking her daughter up from high school.</p>
|
|
|
|
<p>"Hi Mom", she says, "are you still going to teach me to drive today?"</p>
|
|
|
|
<p>"Yep!" she replies. "Let's get going."</p>
|
|
|
|
<p>After ten minutes of driving they arrive at the Chevrolet factory.</p>
|
|
|
|
<p>The girl looks around, puzzled. She asks: "What are we doing here?"</p>
|
|
|
|
<p>The mother smiles and says: "You're in luck, honey, my friend Jim works here at
|
|
the Chevy plant, and he's gonna let you watch a few crash tests of the new
|
|
Malibu! Once you see a few cars smash into each other, I'll take you down to
|
|
the DMV for your driving test."</p>
|
|
|
|
<p>Another common form of "documentation" is the README instructing users to "read
|
|
the tests".</p>
|
|
|
|
<p>Tests aren't docs.</p>
|
|
|
|
<p>Again, let's be clear: once you already know how to use a library, reading the
|
|
tests is <em>very</em> useful. But you need documentation to make you an expert user
|
|
first!</p>
|
|
|
|
<p>You don't learn to drive by watching crash tests. But learning how your car
|
|
behaves during a crash can save your life <em>once you know how to drive</em>.</p>
|
|
|
|
<p>A common argument I see goes something like this:</p>
|
|
|
|
<p>"The tests use the library, so they're a good example of how to use it!"</p>
|
|
|
|
<p>This is true in some very superficial sense, but completely misses the mark.</p>
|
|
|
|
<p>Most of the tests are probably going to deal with edge cases. Edge cases are
|
|
things a normal user won't be encountering very often (otherwise they wouldn't
|
|
be edge cases!).</p>
|
|
|
|
<p>If you're lucky, you might get a test that verifies the library works correctly
|
|
on a normal set of input. But a "normal set of input" is what the users are
|
|
going to be working with the majority the time!</p>
|
|
|
|
<p>Tests simply aren't a good guide to what a user is going to be encountering on
|
|
a day-to-day basis. They can't teach a novice to be an expert.</p>
|
|
|
|
<h2 id="s8-how-to-teach"><a href="index.html#s8-how-to-teach">How to Teach</a></h2>
|
|
|
|
<p>If you accept my idea that the purpose of documentation is to <em>teach</em> users, the
|
|
next question is obviously: "How do I teach my users?"</p>
|
|
|
|
<p>I've been lucky enough to have the chance to teach dancing semi-formally for
|
|
around 6 or 7 years, and lots of various other things informally for a long
|
|
time. The only way to <em>really</em> learn how to teach is to <em>do it</em>.</p>
|
|
|
|
<p>There's no substitute for sitting down with someone face-to-face and teaching
|
|
them something. <strong>If you want to write better documentation, you need to
|
|
practice teaching</strong>.</p>
|
|
|
|
<p>I'm not talking about writing out lesson plans or anything nearly so formal. Do
|
|
you have a hobby (not programming)? If so, spend a couple of hours on a weekend
|
|
teaching a friend about it. You'll get some practice teaching and they'll get
|
|
to learn something new.</p>
|
|
|
|
<p>(If you don't have any non-programming hobbies, maybe you should find some.)</p>
|
|
|
|
<p>If you like photography, teach someone the basics of exposure and composition.
|
|
If you dance, teach them some basic steps. If you play an instrument, teach
|
|
them how to play a simple song. If you like camping, teach them what all the
|
|
gear is for. You get the idea.</p>
|
|
|
|
<p>Don't go overboard. You don't need to give someone a degree, you just need to
|
|
practice teaching a little bit. You need to practice the art of rewiring
|
|
someone's neurons with your words.</p>
|
|
|
|
<p>Once you jump into teaching something (even something simple) you'll probably
|
|
realize that although you know how to do it yourself, it's a lot harder to teach
|
|
someone else.</p>
|
|
|
|
<p>This is obvious when you're working face-to-face with someone. When you tell
|
|
them how to play a C major chord on the guitar and they only produce a strangled
|
|
squeak, it's clear that you need to slow down and talk about how to press down
|
|
on the strings properly.</p>
|
|
|
|
<p>As programmers, we almost <em>never</em> get this kind of feedback about our
|
|
documentation. We don't see that the person on the other end of the wire is
|
|
hopelessly confused and blundering around because they're missing something we
|
|
thought was obvious (but wasn't). Teaching someone in person helps you learn to
|
|
anticipate this, which will pay off (for your users) when you're writing
|
|
documentation.</p>
|
|
|
|
<p>With all that said, I do want to also talk a little about the actual process of
|
|
teaching.</p>
|
|
|
|
<p>The best description of how to teach that I've seen so far is from the book <a href="http://www.amazon.com/dp/069111966X/?tag=stelos-20">How
|
|
to Solve It</a>. Everyone who wants to teach should read this book. The passage
|
|
that really jumped out at me is right in the first page of the first chapter:</p>
|
|
|
|
<blockquote>
|
|
<p>The best [way for the teacher to help their student] is to help the student
|
|
naturally. The teacher should put himself in the student's place, he should
|
|
see the student's case, he should try to understand what is going on in the
|
|
student's mind, and ask a question or indicate a step that <em>could have
|
|
occurred to the student himself</em>.</p>
|
|
</blockquote>
|
|
|
|
<p>This, right here, is the core of teaching. This is it. This is how you do it.</p>
|
|
|
|
<p>People don't learn by simply absorbing lots of unstructured information as it's
|
|
thrown at them. You can't read a Spanish dictionary to someone to teach them
|
|
Spanish.</p>
|
|
|
|
<p>When you want to teach someone you need to put yourself in their shoes and walk
|
|
along the path with them. Hold their hand, guide them around the dangerous
|
|
obstacles and catch them when they fall. <em>Don't</em> carry them. <em>Certainly
|
|
don't</em> just drive them to the destination in your car!</p>
|
|
|
|
<p>The process needs to go something like this:</p>
|
|
|
|
<ol>
|
|
<li>Figure out what they already know.</li>
|
|
<li>Figure out what you want them to know after you finish.</li>
|
|
<li>Figure out a single idea or concept that will move state 1 a little bit
|
|
closer to state 2.</li>
|
|
<li>Nudge the student in the direction of that idea.</li>
|
|
<li>Repeat until state 1 becomes state 2.</li>
|
|
</ol>
|
|
|
|
<p>Too often I see documentation that has very carefully considered step 2, and
|
|
then simply presents it to the reader as a pronouncement from God. That isn't
|
|
teaching. That's telling. People don't learn by being <em>told</em>, they
|
|
learn by being <em>taught</em>.</p>
|
|
|
|
<h2 id="s9-act-3-literate-programming"><a href="index.html#s9-act-3-literate-programming">Act 3: "Literate Programming"</a></h2>
|
|
|
|
<p>The third act opens with a daughter talking to her mother the day before her
|
|
sixteenth birthday.</p>
|
|
|
|
<p>"Hey Mom," she says, "I don't know if you got me a present yet, but if not, what
|
|
I'd <em>really</em> like for my birthday are driving lessons."</p>
|
|
|
|
<p>The mother smiles and says: "Don't worry, it's all taken care of. Just wait for
|
|
tomorrow."</p>
|
|
|
|
<p>The next day at her birthday party she unwraps the present from her mom. Inside
|
|
is a DVD of the show How It's Made. She looks quizzically at her mother.</p>
|
|
|
|
<p>"That DVD has an episode about the factory that builds your car! Once you watch
|
|
the whole thing I'll take you for your driving test."</p>
|
|
|
|
<p>A horrible trend I've noticed lately is using "literate programming" tools like
|
|
Docco, Rocco, etc and telling users to read the results for documentation.</p>
|
|
|
|
<p>Programming languages and libraries are tools. Knowing how a tool was made
|
|
doesn't mean you know how to use it. When you take guitar lessons, you don't
|
|
visit a luthier to watch her shape a Telecaster out of Ash wood.</p>
|
|
|
|
<p>Knowing how your car was built can help you, <em>once you know how to drive</em>.</p>
|
|
|
|
<p>Knowing how your guitar was built can help you, <em>once you know how to play</em>.</p>
|
|
|
|
<p>A common theme throughout these acts/rants is that all of these things I'm
|
|
picking on (source, tests, literate programming, and more) are good things with
|
|
real benefits <em>once you have actual documentation in place to teach users</em>. </p>
|
|
|
|
<p>But until that happens, they're actually <em>bad</em> because they let you pretend
|
|
you've written documentation and your job is done (JKM mentions this in his
|
|
series). Your job is not done until you've taught your users enough to become
|
|
experts. <em>Then</em> they can take advantage of all these extras.</p>
|
|
|
|
<h2 id="s10-the-anatomy-of-good-documentation"><a href="index.html#s10-the-anatomy-of-good-documentation">The Anatomy of Good Documentation</a></h2>
|
|
|
|
<p>The rest of this post is going to be about the individual components that make
|
|
up good documentation. My views are pretty similar to JKM's, so if you haven't
|
|
read the series I mentioned in the first section you should probably do that.</p>
|
|
|
|
<p>In my mind I divide good documentation into roughly four parts:</p>
|
|
|
|
<ol>
|
|
<li>First Contact</li>
|
|
<li>The Black Triangle</li>
|
|
<li>The Hairball</li>
|
|
<li>The Reference</li>
|
|
</ol>
|
|
|
|
<p>There don't necessarily have to be four separate documents for each of these.
|
|
In fact the first two can usually be combined into a single file, while the last
|
|
two should probably be split into many pieces. But I think each component is
|
|
a distinct, important part of good documentation.</p>
|
|
|
|
<p>Let's take a look at each.</p>
|
|
|
|
<h2 id="s11-first-contact"><a href="index.html#s11-first-contact">First Contact</a></h2>
|
|
|
|
<p>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:</p>
|
|
|
|
<ol>
|
|
<li>What is this thing?</li>
|
|
<li>Why would I care about this thing?</li>
|
|
<li>Is it worth the effort to learn this thing?</li>
|
|
</ol>
|
|
|
|
<p>Your "first contact" documentation should explain these things to them.</p>
|
|
|
|
<p>You don't need to explain things from first principles. Try to put yourself in
|
|
the shoes of your users. When you're teaching your teenager to drive, you don't
|
|
need to explain what a "wheel" is. They probably have some experience with
|
|
"things on wheels that you move around in" like lawn mowers or golf carts (or
|
|
even video games).</p>
|
|
|
|
<p>Likewise: if you're creating a web framework, most of the people that stumble on
|
|
to your project are probably going to know what "HTML" is. It's good to err
|
|
a little bit on the side of caution and explain a little more than to assume too
|
|
much, but you can be practical here.</p>
|
|
|
|
<p>Your "first contact" docs should explain what, in plain words, your thing does.
|
|
It should show someone why they should care about that. Will it save them time?
|
|
Will it take more time, but be more stable in exchange? Is it just plain fun?</p>
|
|
|
|
<p>For bonus points, you can also mention why someone might want to <em>not</em> use your
|
|
project. Barely anyone ever mentions the tradeoffs involved with using their
|
|
work, so to see a project do this is refreshing.</p>
|
|
|
|
<p>Finally, the user needs to know if it's worth spending some of their finite
|
|
amount of time on this planet learning more about your project. You should
|
|
explicitly spell out things like:</p>
|
|
|
|
<ul>
|
|
<li>What license the project uses (so they know if it's practical to use).</li>
|
|
<li>Where the bug tracker is (so they can see issues).</li>
|
|
<li>Where the source code is (so they can see if it's (relatively) recently
|
|
maintained).</li>
|
|
<li>Where the documentation is (so they can skim it and get an idea of the effort
|
|
that's going to be involved in becoming an expert).</li>
|
|
</ul>
|
|
|
|
<h2 id="s12-act-4-read-the-docstrings"><a href="index.html#s12-act-4-read-the-docstrings">Act 4: "Read the Docstrings"</a></h2>
|
|
|
|
<p>Scene four. A father is finally making good on his promise to give his daughter
|
|
driving lessons.</p>
|
|
|
|
<p>"Okay Dad," she says, "I'm ready. I've never driven a car before. Where do we
|
|
start?"</p>
|
|
|
|
<p>A woman in her mid-forties walks through the door. "Who's this?" the daughter
|
|
asks.</p>
|
|
|
|
<p>"This is your driving teacher, Ms. Smith." the father replies. "She's going to
|
|
sit in the passenger seat with you while you drive the two hour trip to visit
|
|
grandpa. If you have any questions about a part of the car while you're
|
|
driving, you can ask her and she'll tell you all about that piece. Here are
|
|
the keys, good luck!"</p>
|
|
|
|
<p>In languages with <a href="https://en.wikipedia.org/wiki/Docstring">docstrings</a> there's a tendency to write great docstrings
|
|
and call them documentation. I'm sure the "doc" in the word "docstrings"
|
|
contributes to this.</p>
|
|
|
|
<p>Docstrings don't provide any organization or order (beyond "the namespace they
|
|
happen to be implemented in"). Users need to somehow know the name of the
|
|
function they need to even be able to <em>see</em> the docstring, and they can't know
|
|
that unless you <em>teach</em> them.</p>
|
|
|
|
<p>Again, docstrings are great <em>once you know the project</em>. But when you're
|
|
teaching a novice how to use your library, you need to guide them along they
|
|
way and not sit back and answer questions when they manage to guess a magic
|
|
word correctly.</p>
|
|
|
|
<h2 id="s13-the-black-triangle"><a href="index.html#s13-the-black-triangle">The Black Triangle</a></h2>
|
|
|
|
<p>The next important piece of documentation is <a href="http://rampantgames.com/blog/2004/10/black-triangle.html">the "black triangle"</a>. It
|
|
should be a relatively short guide to getting your project up and running so the
|
|
user can poke at it.</p>
|
|
|
|
<p>This serves a couple of purposes. First, it lets the user verify that yes, this
|
|
collection of bytes is actually going to run and <em>do something</em> on their
|
|
machine. It's a quick sanity check that the project hasn't bit rotted and is
|
|
still viable to use at that point in time. More importantly, it lets your
|
|
prospective user <a href="http://worrydream.com/LearnableProgramming/#react">get some paint on the canvas</a>.</p>
|
|
|
|
<p>Imagine if you went to your first guitar lesson and the teacher said: "Okay,
|
|
we're going to start by learning 150 different chords. Then in about six months
|
|
we can play some songs." No guitar teacher does that. They teach you three
|
|
chords and give you a couple of cheesy pop songs to play. It helps the student
|
|
get a feel for what being a guitarist as a whole is going to be like, and it
|
|
gives them something to help keep their interest.</p>
|
|
|
|
<p>Your "black triangle" documentation should be a short guide that runs the user
|
|
through the process of retrieving, installing, and poking your project or
|
|
language.</p>
|
|
|
|
<p>"Short" here is a relative word. Some projects are going to require more setup
|
|
to get running. If the benefits are enough to justify the effort, that's not
|
|
necessarily a problem. But try to keep this as short as possible. <em>Just get
|
|
something on the screen</em> and move on.</p>
|
|
|
|
<h2 id="s14-act-5-read-the-api-docs"><a href="index.html#s14-act-5-read-the-api-docs">Act 5: "Read the API Docs"</a></h2>
|
|
|
|
<p>Our next scene opens a year after the last, with the father from the last scene
|
|
talking to his son.</p>
|
|
|
|
<p>(Sadly, the daughter in that scene died in a car crash because she didn't know
|
|
to ask Ms. Smith about seatbelts before getting on the expressway. Ms. Smith
|
|
was wearing hers, of course.)</p>
|
|
|
|
<p>"Okay son, I know you're a little scared of driving because of what happened to
|
|
your sister, but I've fixed the problem."</p>
|
|
|
|
<p>He hands the young man an inch-thick book. "Asking Ms. Smith questions along
|
|
the way clearly didn't work, so we had her write out a paragraph or two about
|
|
each piece of your car. Go ahead and read the entire manual cover to cover and
|
|
then drive down to see grandpa."</p>
|
|
|
|
<p>API documentation is like the user's manual of a car. When something goes wrong
|
|
and you need to replace a tire it's a godsend. But if you're learning to drive
|
|
it's not going to help you because <em>people don't learn by reading alphabetized
|
|
lists of disconnected information</em>.</p>
|
|
|
|
<p>If you actually try to teach someone to use your project face-to-face, you'll
|
|
probably find yourself talking about things in one namespace for a while, then
|
|
switching to another to cover something related, then switching back to the
|
|
first. Learning isn't a straight path through the alphabet, it's a zig-zaggy
|
|
ramble through someone else's brain.</p>
|
|
|
|
<h2 id="s15-the-hairball"><a href="index.html#s15-the-hairball">The Hairball</a></h2>
|
|
|
|
<p>This brings me to the next type of documentation: "the hairball". By now the
|
|
user has hopefully seen the "first contact" docs and the "black triangle" docs.
|
|
You've got them hooked and ready to learn, but they're still novices.</p>
|
|
|
|
<p>The "hairball" is the twisted, tangled maze of teaching that is going to take
|
|
these novices and turn them into expert users. It's going to mold their brains,
|
|
one nudge at a time, until they have a pretty good understanding of how your
|
|
project works.</p>
|
|
|
|
<p>You'll usually want to organize the "hairball" into sections (unless this is
|
|
a very small project). These sections will probably <em>kind of</em> line up with
|
|
namespaces in your project's public API, but when it makes sense to deviate you
|
|
should do so.</p>
|
|
|
|
<p>Don't be afraid to write. Be concise but err on the side of explaining a bit
|
|
too much. Programmers are pretty good at skimming over things they already
|
|
know, but if you forget to include a crucial connection it can leave your users
|
|
lost and stumbling around in the woods.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>This is where your hobby-teaching practice and your reading of How to Solve It
|
|
are going to come in handy. Put yourself in a user's brain and figure out each
|
|
little connective leap they're going to need to make to become an expert.</p>
|
|
|
|
<h2 id="s16-act-6-read-the-wiki"><a href="index.html#s16-act-6-read-the-wiki">Act 6: "Read the Wiki"</a></h2>
|
|
|
|
<p>In the penultimate scene, a mother has signed her teenage son up for an
|
|
after-school driving class.</p>
|
|
|
|
<p>On the first day, the teacher hands them a syllabus detailing what they're going
|
|
to cover, talks about grading, and sends them home a bit early.</p>
|
|
|
|
<p>On the second day, she gives them a brief overview of the various pieces of
|
|
a car and how they work together. She also talks about a few of the most
|
|
important laws they'll need to be aware of.</p>
|
|
|
|
<p>On the third day, the teacher calls in sick and they have a substitute. He
|
|
covers the material for half of the fifth day in the syllabus. He has to leave
|
|
early, so he brings in his nineteen year old daughter to finish the class.
|
|
She covers the first half of the fourth day's material.</p>
|
|
|
|
<p>The fourth day the students arrive to find a note on the door saying the class
|
|
has been cancelled because the teacher is still sick and they can't find
|
|
a substitute. There's a note saying "TODO: we'll talk about the material
|
|
later."</p>
|
|
|
|
<p>The fifth day the teacher has partially recovered, so she returns and covers the
|
|
material for the fifth day. It's a bit hard to understand her because she's had
|
|
half a bottle of Nyquil and is slurring most of her words and keeps saying
|
|
"cat" instead of "car".</p>
|
|
|
|
<p>All the students fail the driving test.</p>
|
|
|
|
<p>Wikis are an abomination. They are the worst form of "documentation".</p>
|
|
|
|
<p>First of all: assuming they work as intended, they have no coherent voice.</p>
|
|
|
|
<p>Have you ever taken a class with multiple teachers at once? Probably not,
|
|
because it doesn't work very well (with exceptions for things like partnered
|
|
dancing where there are distinct lead/follow parts).</p>
|
|
|
|
<p>Worse still: have you ever taken a class where there's one jackass in the room
|
|
who keeps constantly raising his hand and offering his own (often incorrect)
|
|
opinions? Wikis are like that, except they <em>actively encourage</em> random people
|
|
to interrupt the teacher with their own interjections.</p>
|
|
|
|
<p>I can hear the objections now: "But putting our docs on a wiki means <em>anyone</em>
|
|
can fix typos!"</p>
|
|
|
|
<p>Jesus. Christ.</p>
|
|
|
|
<p>"It makes it easy to fix typos" is a horrible argument for using a wiki.</p>
|
|
|
|
<p>First of all, as JKM says, you should have an editor (or at least someone to
|
|
proofread) which will catch a lot of the typos.</p>
|
|
|
|
<p>And even if there <em>are</em> typos, they're one of the least important things you
|
|
need to worry about anyway. Misspelling "their" isn't going to impact the
|
|
effectiveness of your teaching very much. Your lessons being a disorganized
|
|
mess because they were written by three different people across six months <em>is</em>
|
|
going to make them less effective.</p>
|
|
|
|
<p>Keeping your documentation in a wiki also makes it hard or impossible to keep it
|
|
where it belongs: in version control right alongside your code.</p>
|
|
|
|
<p>But all that is irrelevant because aside from Wikipedia itself and video game
|
|
wikis, <em>they don't fucking work</em>.</p>
|
|
|
|
<p>The project maintainer sets up a wiki, sits back and pats herself on the back
|
|
saying: "I have set up a way for other people to do this boring job of writing
|
|
documentation for me. Now we wait." </p>
|
|
|
|
<p>Maybe one or two people fix some typos. A dude who thinks he understands
|
|
a topic but actually doesn't writes some completely wrong docs. Maybe they get
|
|
reverted, maybe they don't.</p>
|
|
|
|
<p>The project changes. A new user reads some of the (sparse) documentation which
|
|
is now out of date. Eventually they discover this and complain only to be met
|
|
with: "Well it's a wiki, fix it yourself!"</p>
|
|
|
|
<p>It is not the responsibility of the student to fix a broken lesson plan. For
|
|
fuck's sake, <em>the entire point of having a teacher</em> is that they know what the
|
|
students need to learn and the students don't!</p>
|
|
|
|
<p>It's completely okay to ask your students for criticism so you can improve your
|
|
lesson plan. Asking "what parts did you find difficult?" is fine. It's another
|
|
thing entirely to ask them to <em>write your lesson plan for you</em>.</p>
|
|
|
|
<p>Seriously: fuck wikis. They are bad and terrible. Do not use them. Take the
|
|
time and effort to write some real documentation instead.</p>
|
|
|
|
<h2 id="s17-the-reference"><a href="index.html#s17-the-reference">The Reference</a></h2>
|
|
|
|
<p>The final type of documentation is "the reference". This section is for the
|
|
users who have traveled through the "hairball" and made it to the other side.
|
|
They're now your experts, and the reference should support them as they use your
|
|
project in their daily work.</p>
|
|
|
|
<p>This section should contain things that experienced users are likely to need,
|
|
such as:</p>
|
|
|
|
<ul>
|
|
<li>"API documentation" for every user-facing part of your project.</li>
|
|
<li>A full changelog, with particular attention to backwards-incompatible changes
|
|
between versions.</li>
|
|
<li>Details about the internal implementation of the project.</li>
|
|
<li>Contribution policies (if your project accepts outside contributions).</li>
|
|
</ul>
|
|
|
|
<p>Tools like JavaDoc can produce something that looks like the first, but I share
|
|
the same opinion as Jacob Kaplan-Moss:</p>
|
|
|
|
<blockquote>
|
|
<p>Auto-generated documentation is almost worthless. At best it's a slightly
|
|
improved version of simply browsing through the source, but most of the time
|
|
it's easier just to read the source than to navigate the bullshit that these
|
|
autodoc tools produce. About the only thing auto-generated documentation is
|
|
good for is filling printed pages when contracts dictate delivery of a certain
|
|
number of pages of documentation. I feel a particularly deep form of rage
|
|
every time I click on a "documentation" link and see auto-generated
|
|
documentation.</p>
|
|
|
|
<p>There's no substitute for documentation written, organized, and edited by
|
|
hand.</p>
|
|
</blockquote>
|
|
|
|
<p>Yes, you can probably find a tool to read your project's source and shit out
|
|
some HTML files with the function names in them. Maybe it will even include the
|
|
docstrings!</p>
|
|
|
|
<p>I would still urge you to write your API docs by hand. It's going to be
|
|
a little more typing, but the results will be much better for a number of
|
|
reasons.</p>
|
|
|
|
<p>API docs and docstrings, while similar, serve different purposes. Docstrings
|
|
have to provide what you need in the heat of coding in a REPL-friendly format.
|
|
API docs can afford the luxury of a bit more explanation, as well as links to
|
|
other things the user might want to know while browsing them on their couch.
|
|
API docs should also be Google-friendly.</p>
|
|
|
|
<p>A common objection here is that you're going to be retyping a lot of words.
|
|
Copy and paste mostly solves that problem, and learning to type makes the rest
|
|
a non-issue.</p>
|
|
|
|
<p>Some will say: "But copy and pasting is evil! You're duplicating effort! How
|
|
will you keep the changes in the docstrings and the API docs in sync if they
|
|
change?"</p>
|
|
|
|
<p>My opinion here is that if your public-facing API is changing often, you're
|
|
probably going to be making your users' lives harder when they need to
|
|
constantly update their code to work with yours. So the least you can do is
|
|
make <em>your</em> life a little harder to provide them with the best documentation
|
|
possible to help ease the pain.</p>
|
|
|
|
<p>Auto-generated documentation has no coherent voice. It pulls in everything in
|
|
the code without regard for overall structure and vision. You can <em>probably</em>
|
|
get away with it for the API docs in your "reference" documentation, or you
|
|
could take some pride in your work and write the best docs possible!</p>
|
|
|
|
<h2 id="s18-act-7-a-new-hope"><a href="index.html#s18-act-7-a-new-hope">Act 7: "A New Hope"</a></h2>
|
|
|
|
<p>The final act of our play is set in a mall parking lot on a Sunday afternoon.
|
|
A single car is in the parking lot. Inside is a family: a mother and father who
|
|
are teaching their son to drive.</p>
|
|
|
|
<p>They start by driving the car into the middle of the lot, away from any
|
|
obstacles. The son gets into the driver's seat, and the parents explain briefly
|
|
what the main controls do. They let him drive around the empty lot a bit to get
|
|
a feel for how the car works.</p>
|
|
|
|
<p>When it's time for him to park he shifts to park and takes off his seatbelt.
|
|
His mom reminds him of the control called a "parking brake". He realizes that
|
|
he should use this when parking. A set of neurons is now linked in his brain
|
|
and he will remember to use the parking brake properly for the rest of his life.</p>
|
|
|
|
<p>Over time the parents take their son driving many times, always being sure that
|
|
they're putting him into situations he can handle (but will still learn from).
|
|
He drives on a road, then learns to parallel park, then drives on a highway.</p>
|
|
|
|
<p>He has questions along the way. Sometimes the parents are ready with an answer.
|
|
Sometimes the questions reveal something else missing deeper down in his
|
|
knowledge which the parents correct.</p>
|
|
|
|
<p>Over time he learns more and more. He gets his license and begins driving on
|
|
his own.</p>
|
|
|
|
<p>When he gets a flat tire he reads the owner's manual and fixes it.</p>
|
|
|
|
<p>He watches the How It's Made episode about his car because he's curious how the
|
|
brakes which saved his life at a stop sign last week actually work.</p>
|
|
|
|
<p>His windshield wipers stop working one day. He opens up the hood and figures
|
|
out the problem, fixing it himself.</p>
|
|
|
|
<p>One day he is hit by a drunk driver. He walks away with only bruises. He never
|
|
saw the countless crash tests the engineers performed to create the airbag
|
|
system, but they saved his life.</p>
|
|
|
|
<p>In the last scene we see the son many years later. His hair is a bit gray now,
|
|
but otherwise he looks a lot like the teenager who forgot to use the parking
|
|
brake.</p>
|
|
|
|
<p>He's in a car with his teenage daughter, and he's teaching her how to drive.</p>
|
|
</article></main><hr class='main-separator' /><footer><nav><a href='https://github.com/sjl/'>GitHub</a> ・ <a href='https://twitter.com/stevelosh/'>Twitter</a> ・ <a href='https://instagram.com/thirtytwobirds/'>Instagram</a> ・ <a href='https://hg.stevelosh.com/.plan/'>.plan</a></nav></footer></body></html> |