Teach, Don’t Tell (2013) | Hacker News Reader

Teach, Don’t Tell (2013)

stevelosh.com

135 pointsTomte18 comments

This is a great read and it articulates my own frustration with the current practice-de-jour of "we write such readable code that we don't need documentation". While readable code is great, I still don't want to have to read the whole codebase to figure out how to use something.

I've found it useful to take lessons from Kathy Sierra's excellent "BADASS: Making Users Awesome" book. Look, folks, people don't want to use your library because the library itself is awesome - they want to use it to make something awesome for themselves, or to do something that makes them look awesome. Focus on how a new user can use your library/tool to accomplish what they want, not just a laundry list of explaining features.

Apply some of the marketing wisdom and user empathy resources and you will be so far ahead of 90% of the libraries/tools/internal code that exists today.

Kathy gave a talk at Business of Software a couple years back on the same topic. Well worth an hour of your time: https://vimeo.com/54469442

This is an extremely good article and echoes a lot of the frustration I've experienced in the last 6 months while trying to get up to speed in the current webdev world.

A git repo with a basic example is NOT a tutorial and teaches very little.

I greatly appreciate all the boilerplates / examples people put out there. I really do, I've spent a lot of time digging through them and have learned a great deal. However it is very inefficient. While they show the "what" to do, they often neglect the "how" and the "why".

While I agree almost entirely with the article...

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

As a counterpoint, a well-maintained wiki in the right situation can make the difference between confusion and enlightenment. A wiki isn't a substitute for proper documentation, but it can be an effective supplement for things like "the docs didn't cover this particular corner case very well, so here's what I did to resolve it, and if anyone can improve on it, have at it".

I also disagree with the assertions that wikis as documentation (instead of as a supplement thereof) are inherently bad in and of themselves, but I do agree that they won't magically populate themselves; the authors of the system in question would be wise to produce the wiki's content themselves and be actively monitoring for erroneous edits, at which point - as the author suggests - said documentation might as well be checked into version control alongside the rest of the code.

I agree. A coherent narrative helps to teach newcomers or old timers who want to sharpen their saws.

A crowd is at a tremendous disadvantage when called upon to provide a singular vision. The crowd shines when a job demands completeness.

Once the newcomers or old hands take their lessons and return to their work, they're going to run into unpredictable issues that would require a tremendous breadth of coverage for any one knowledge source to handle. That's where a wiki like the one for Arch can be a big help.

Leo Horie's documentation and tutorials for Mithril are one of the best examples I've run across of truly stellar documentation. Not coincidentally, reading through it all, you learn a lot not only about the library but also about good programming techniques in general.

In the same vein, there's React-DND by Dan Abramov. The tutorial is probably one of the best React tutorials out there. It teaches good ideas about how to architect your app (think about state etc.) apart from how to use the library effectively. Highly recommended for anyone who's working with React.

http://gaearon.github.io/react-dnd/examples-chessboard-tutor...

link: http://mithril.js.org/getting-started.html

The "Learn" section (the blog, actually) is also very good.

I wish I could learn to write like that.

I don't know how Leo leveled up, but really, there are two things you need to do to improve your style:

Figure out what to practice, then practice :-)

That's what I'm currently doing with j2c, a small js library.

After writing the core (JS object to CSS compiler) in a couple of evenings, I decided to play the open source game, polish the API, bullet-proof the test suite and write good docs. That took much more time, and I'm not fixed yet on the final API.

I have a maxim: "If it's not documented, it doesn't exist". Programmers can spew out lines of code to their hearts content, but if you don't tell people what it's used for and how to use it, it's just going to be ignored by the next guy.

Off topic: Does anyone know where Steve is nowadays? He hasn't posted anything in a while and seems to be away from Github also[0]. I loved his Clojure series[1] and really hope he's fine and that he gets back to writing!

[0] - https://github.com/sjl/

[1] - http://stevelosh.com/blog/2012/07/caves-of-clojure-01/

I haven't been on-the-grid much lately for a couple of reasons:

* Doing a lot more meatspace stuff (guitar, bass, photography, etc). * Getting ready to move to Iceland to go back to grad school in the fall.

Once things calm down with the move I'll likely be writing/coding publicly a lot more again.

As someone who has stolen a lot of Vimscript from his dotfiles, I know that he prefers Mercurial to git (see https://github.com/sjl/dotfiles), and so he's more active on Bitbucket than Github.

You can find a link to his Twitter on his About page - he tweeted as recently as yesterday.

Thanks! Just tweeted back to him.

He tweeted yesterday that he's moving to Iceland in August for grad school.

What's the best way to document the code? I'm starting to set up doxygen for the team and could not find anything "better", we do mostly c/c++, with some js/html/css for frontend.

Reply on news.ycombinator.com