Minimum Viable Snippet
Learning a new programming language, library or framework can be difficult. It often takes an incredible amount of patience, time and persistence to properly learn something new and of even moderate complexity. Given this unavoidable commitment, programmers are often reticent to choose one option over another. Granted, programmers looking to transition away from .NET as a career choice probably has all the motivation they need to learn Java and the popular products of its ecosystem. However, for the casual, autodidact or adventurous programmer presented with a cyclopean mountain of choice, there is, on the surface, little reason to choose one option over another. Therefore, like many choices chosen by computerists, there is a strong desire to cut corners in their learning, or at least receive as much help as possible along the way.
One extremely simple way that a software designer or community can help the neophyte is what I like to call the Minimum Viable Snippet. The Minimum Viable Snippet is a tiny fragment of source code that adheres to the following properties:
- It’s located on the landing page of the main software site.
- It is typically located in a way that draws the eye.
- It is fervently representative of the library, language or framework.
- It’s short and sweet and as elegant as possible; either self-evident in its intent or minimally explained via commentary.
While you will not always find that the Minimum Viable Snippet is given a place of central focus (point #2), the less scrolling required to see it the better. An important point about #3 is that under no circumstances should the Minimum Viable Snippet be a “Hello World” example. You can do better, but it might require some thought. Take some time to think up a snippet that illustrates what your software is all about. Finally, #4 is important because it really highlights the essential nature of your software or language. That is, if the Minimum Viable Snippet is 500 lines long, then it gives the prospective user a notion of what kind of pain they can expect. Likewise, if the snippet is without commentary, then a programming language like J is fighting an uphill battle.
There are some excellent examples of Minimum Viable Snippets to take inspiration from:
Regardless of your feelings about Node.js, it’s MVS fits almost all of the criteria listed above.
Ruby’s Minimum Viable Snippet is positioned perfectly, is nicely commented, and is lovely. Sadly it’s a “Hello World”, but at least it’s nicely motivated by the commentary.
One of my favorites is the MVS on the Sinatra homepage. It could stand to be syntax highlighted, but otherwise it’s near perfect.
The programming language Roy has no MVS, but it has something else entirely; an operational programming console on the page itself. However, it would be nice to see some code prepopulating the console, awaiting one to hit the enter key.
The contracts for Java library Cofoja has a nice MVS on its landing page. As a bonus, it’s highly representational of the library itself and the philosophy of DbC.
Other nice examples (not comprehensive) include: Akka, jADT, Joda Time, Knockout.js. Comment below if you know of more.
So should we choose our programming languages and frameworks based solely on the MVS alone? Absolutely not, but it benefits the user to see a carefully chosen example of use from the start in order to save them some precious cycles trying to track one down. Likewise it benefits the creator and community supporting the software to provide a low-pass filter for those who are likely to dismiss a system or language over its Minimum Viable Snippet. Everyone wins.
It’s one of the few things in software that is a no-brainer.
:F
22 Comments, Comment or Ping
Rich Hickey
Should books have a minimum viable snippet on the cover as well? No need for the Book Review then! People who make decisions with minimal information get minimal results.
Aug 23rd, 2012
Eric Budd
100 times this. There is nothing more frustrating than trying to get a quick overview of a language and faceplanting into wall of changelogs and installation instructions, or worse, irrelevant salesmanship. Show me the code!
Aug 23rd, 2012
Darrin Thompson
I’ll have to take their word for it, since I don’t know much about tensors:
http://redberry.cc/index.html
Aug 23rd, 2012
mnicky
A few languages with nice MVS:
http://moonscript.org http://racket-lang.org http://gosu-lang.org
http://ioke.org has even self describing MVS ;)
Aug 23rd, 2012
fogus
@Rich
Absolutely correct. This is the “low-pass filter” that I mentioned. Books do have an MVS on the cover usually, the back cover at least – it’s the book summary. The only way to know if the book is truly worthwhile is to read it. Even a review is a form of filter. Likewise, with a language the only way to know if it works for you is to use it seriously, but MVS, code examples, word of mouth and blog posts help to give a notion if it’s worth the commitment.
Aug 23rd, 2012
Rich Hickey
@fogus
A book summary is not a snippet. Imagine if an author were asked to put a few of their best sentences on the back cover. I think they’d balk, and for good reason.
Aug 23rd, 2012
vemv
I reckon that not all technologies can benefit from a MVS. For instance, Clojure or Haskell require more of a slow, conceptual trip.
Aug 23rd, 2012
fogus
@Rich
My idea of an MVS is not meant to trivialize a language or library. Instead, when done well I find it a highly effective marketing technique. I’m willing to admit that this is a matter of opinion and probably not possible to achieve in every case. I should say that the absence or presense of a MVS in no way reflects on the quality of a system.
Aug 23rd, 2012
Pierre Chapuis
@Rich http://37assets.s3.amazonaws.com/svn/rework-cover-back-big.png
Aug 23rd, 2012
Stuart Sierra
I’m suspicious of snippets because they only demonstrate surface qualities: syntax, whitespace, and what typeface the snippet was printed in. If I see something apparently designed to optimize those attributes, I worry that not enough time was spent designing the less-visible qualities like correctness, flexibility, and performance.
On the other hand, I agree that subjective impressions matter for marketing. As someone once said, “A bad idea with good presentation is doomed eventually. A good idea with bad presentation is doomed immediately.”
Aug 23rd, 2012
Barney
@Rich:
So in your opinion, do minimum viable snippets actually create any harm? How far are you willing to downgrade their use?
“Imagine if an author were asked to put a few of their best sentences on the back cover.” So are you saying that programming websites (for languages or libraries) should hide their best snippets in order to get people to buy them?
@Stuart Sierra: I don’t agree that syntax is a surface quality, it is an important aspect regarding simplicity.
Aug 23rd, 2012
Patrick Logan
I have a set of significant exercises I’ve used several times to learn a programming language or library.
To learn a new programming language, I will implement a tail-call friendly Scheme interpreter with full first-class continuations. Having done this for the first time 25 years ago, and several times since, I can get this done in a weekend of programming with the usual family interruptions, shopping, cooking, walks, etc. to allow thoughts to brew in between coding sessions.
These particular aspects of Scheme tend to emphasize the features or lack there-of in the new language. This also emphasizes how more or less imperative and more or less functional the language is. I’ve yet to try this with languages significantly different from C or Lisp. I should try it with Prolog or J or something further afield.
Aug 23rd, 2012
Brian Cooley
I think one thing worth keeping in mind is that choosing a programming language is not a discrete decision but rather the culmination of a series of small decisions.
In that sense, it’s a lot like reading a book. Every paragraph offers the reader the choice of continuing or abandoning his efforts.
But I think the metaphor breaks down a little there. Books are linear. When a reader has gotten far enough to read a summary or snippet on the cover, it’s trivial (even for most digital versions these days) for him to investigate further, and it’s obvious where to start. In fact, it’s an often repeated adage that the opening paragraph is incredibly important to a book’s success. It’s supposed to set the hook and build momentum to get the reader to the later chapters. It doesn’t matter how good the fourth chapter is if no one ever gets that far.
Maybe in that same vein this idea of an MVS is to set the table in the same way the opening paragraph should. Maybe it becomes a de facto starting point, and maybe it gives a chance to set the hook and build momentum.
If I can torture this metaphor for one final point, while an author might not want to be judged on a snippet of his book, I’ve never heard an author say he only wants readers who are committed to reading at least the first five chapters. Minimal results might come from minimal information, but sufficient information only comes one piece at a time.
Aug 23rd, 2012
Tim Schafer
To be fair the Ruby site MVS rotates, so it’s not always “Hello World”.
With all the great MVS examples given, what does it say that the only link I really dug into from the post was for J. I believe I dismissed J in the past because it wasn’t open source, but am happy to see that’s no longer the case. I suppose they could slap the tacit quicksort example from http://en.wikipedia.org/wiki/J_(programming_language) on the homepage. Though without commentary, the example would be pointless ;)
Aug 23rd, 2012
un_passant
I’m actually on the fence about MVS. On one hand, like (I believe) R.Hickey, there is no way that one can understand easily (and immediately) the most important aspects of a new programming language. Because these most important aspects will be the way they (eventually) shape our thought by introducing new concepts and/or new synergies between concepts. No blub[pg] programmer will ever fall for a lisp MVS.
On the other hand, there can’t be anything wrong with efficient marketing !
So maybe one should also cater for the impatient (aren’t we all time constrained ?) but nevertheless be very explicit about the fact there is much more than meets the eye on the MVS.
Cheers !
[pg] http://www.paulgraham.com/avg.html
Aug 23rd, 2012
William Taysom
AngularJS http://www.angularjs.org/ has an excellent progression of minimum viable snippet. They have, I would argue, the perfect landing page.
Aug 23rd, 2012
Thom Chiovoloni
Factor has a randomly chosen one on their homepage: http://factorcode.org/ . Some of them are extremely elegant.
Aug 24th, 2012
jason
“I find it a highly effective marketing technique.”
Agreed. Maybe your worth more than a 60 second explanation; maybe the other guy is stupid for not investing more time in hearing why you’re so great (in your mind of course, not his); but if you’re in a elevator and someone actually asks for pitch (or comes to your website), the proper response is your best face/sell/example and not “Sorry but if you’re not willing to spend a week to find out, I got nothing to say to you”.
A book’s title sells its worth. If you like the title, you read the subtitle. If you like the subtitle, you read the blurbs. Like those? You flip through the pages. You buy the book and spend the next week learning.
Aug 25th, 2012
William S
It’s not just a marketing technique, its a communication technique. It’s designed to answer one of users primary questions when they come across a project’s website: how do I get started, and why should I bother? The best way to get people interested is to get them to write a little code and feel like their might be a solution to some of their problems there. It’s goal should be to get interested in learning more.
When someone come across your project page the first time their agenda is probably somewhere between “research alternatives for monolithic Java or Rails app” to “check out neat thing John mentioned” all the way down to “browzin interwebzzz.” If you contrast this to Fogus’ approach to reading books which I’d partially summarize as “bring your own agenda.” It’s pretty clear the site needs to do offer something more actionable.
Very few people are using MVS for decision making solely based on MVS for important projects. More likely is they are just defaulting to their (or their bosses/friends) old safety-blanket tech. Hopefully instead they might weigh some new options they’ve downloaded, played with and research more thoroughly. Having a good MVS helps get you into that group, not having one will probably exclude you from it for many users, at least until you gain enough traction that others users start blogging/producing MVS examples for you.
Aug 28th, 2012
Russ Olsen
I really like the idea of MVS and, more importantly, the existence of an MVS is one of the ways that I do tend to decide what the spend my time on. For me it has less to do with marketing or technical quality and more an answer to the question “Do the people behind this project know how to explain it”? Cause without an explanation code is just so many bytes.
Sep 27th, 2012
Antoine Comte
The Rust programing language website also has a nice MVS http://www.rust-lang.org/
Oct 23rd, 2012
tompa
Apache’s software is (sadly) very anti-MVS, for example: http://ant.apache.org/
Nov 8th, 2012
Reply to “Minimum Viable Snippet”