Code As Media, AndrewOdewahn

This is a catalog of sites where code is a media object in and of its own right.We’re not interested so much in the code itself (i.e., does it work, how does itperform, etc), but how do we communicate about code: what are the best waysto see, learn, and understand a topic. People are learning in new ways, and wewant to understand the patterns that are emerging.

Each chapter covers a specific pattern, along with multiple sample sites thatshow the ideas in action. The goal is to begin to build a common vocabulary tothink about new ways people are learning to code and to understand the rangeof projects across the web. The current patterns are:

• Unstructured Sandbox. An unstructured sandbox allows you to try yourcode right in the browser, but does not force or require you to take anyspecific actions before you can proceed to the next step.

• Structured Sandbox. Sites that provide a structured sandbox also allowyou to try code in the browser, but proscribe how you step through mate-rial. You typically have a very specific exercise to complete before you canproceed to the next step in the learning process.

• Live Stack. Examples of full language and tool stacks, that might eitherbe in-browser, PaaS, or downloadable environments.

• Sharing. Examples of how code can be shared with others for commenta-ry and discussion.

• Formatting and Annotation. Examples of decorating the code listing forimproved readability.

• Execution and Flow. Examples that illustrate how the execution or struc-ture of code.

• Finding and Searching. Examples of sites related to finding specific ex-amples or reference material.

• Evolution. Examples of how code is shown to change or evolve over time.

1

1

Each pattern has 4 to 5 canonical examples. The final chapter lists sites thatapply these ideas, or are just really interesting. You can find this at:

• Projects

Segmenting Learners {#_segmenting_learners}

We think of “beginner” and “expert” in a topic rather one dimensionally. You’reeither a beginner in JavaScript, or you’re an expert. But, there are really two di-mensions: the one we just noted (someone’s knowledge of a specific topic) andthe background knowledge they already bring to that area. ? illustrates thisbreakdown.

Here are a few observations on the 4 quadrants:

• Quadrant I is for people who don’t know a language and don’t have anyprior experience. This is probably Codecademy’s core audience — peopleseeking step by step with as few distractions as possible. So, things like“Download this file and run something in the terminal” or “Open the filein a text editor” are way beyond what their capacity. They’ve never evenheard of this stuff. This is why codecademy is so compelling to these peo-ple — you can get an immediate win without being frustrated by a bunchof things you don’t know.

• Quadrant II is for people who have become familiar with a topic, butthey’ve not really deeply mastered it in any way. So, you might have gonethrough all the Codecademy courses and earned all the badges, but you

CHAPTER 1: Code As Media, Andrew Odewahn

2

still have no idea what a text editor is, how to use git (or maybe even acommand line), or git. Basically, you know a tool but not the whole eco-system of tools required to actually do anything useful. This might also bewhere first year ITP students are — you can do some great stuff in a con-tained environment like processing, but there’s a host of other back-ground info (git, heroku, sublime, data structures, etc) that you haven’tquite mastered.

• Quadrant III is for people who are starting to learn a new topic, butthey’ve already mastered one other toolset in it’s entirety. So, these arepeople who are new to Ruby, but already know Python. You don’t have totell people how to use a text editor or what the command line is — theyalready know it and it’s assumed. For these people, an unstructuredsandbox is fine — they want to focus on the language or idea, and they’llworry about the environment later. They might also want a virtual imageto play around with that’s already pre-configured, just to jumpstart theprocess.

• Quadrant IV is for people who are experts in a topic and also deeply un-derstand the tools. These are people for whom a virtual image is a conve-nience, but they’d probably be just as happy with some minimalist in-structions. These are people,in Adam’s earlier comment, are reading en-tire books about pointers in C.

Contributing

This book is licensed under a Creative Commons Attribution-NonCommercial4.0 International License. I encourage you to fork my work and make your ownimprovements under the terms of the license. If you have any changes you wantto send back our way, please make a regular pull request via Github. If theauthors like your changes, they may integrate them into the official repo andgive you a credit. If you just have an issue to report, please use the regular Git-hub issue system.

Running the site locally

The site uses harpjs to build a site and Atlas to build the PDF, mobi, and epub.To build the site:

• Install harp.• Clone the repo

• Run harp server --port 4567

Contributing

3

When you want to build the site, clone the repo down again into another di-rectory, create a gh-pages branch, and then run harp compile . _new di-rectory_

CHAPTER 1: Code As Media, Andrew Odewahn

4

Structured Sandbox

These sites, which are typically geared towards beginners learning a languageor tool, provide a guided introduction using a live code sandbox. For example,you’re asked to declare a variable of a certain type, compute a certain value, orperform some task on a data structure (like reverse an array). Typically, thesesteps are executed using some sort of testing suite to confirm that the user per-formed the task.

• Strengths

◦ Highly interactive. A user usually cannot progress until they’ve suc-cessfully completed the coding step.

◦ Granularly structured. The courses are usually very well structured,based around tasks or specific exercises.

◦ Game-ifable. It’s very simple to award badges and whatnot basedon completion.

• Weaknesses

◦ Complex to develop. The test suites require a specialized authorwho can write the tests.

◦ Rigid. These tend towards lowest common denominator topics thatcan only be expressed in simple, step-by-step tasks

◦ Tend to be slow and plodding, and it’s difficult (impossible, really)to jump around. A professional wants to be able to extract reliableinformation quickly, make connections, refer back to other parts ofthe docs, etc.

Examples include:

Codecademy

Codecademy offers tutorials in JavaScript, Python and Ruby. The tutorials arevery tightly structured into small chunks, each with an associated action (like

5

2

defining a string). The author uses their custom CMS to create both the narra-tive material as well as the “unit tests” that describe the correct answer. Whilethe classes have generated a lot of buzz and garnered many signups, they havea high incompletion rate.

Code School (Rails for Zombies, Try Objective-C,etc.)

CodeSchool, like codecademy, provides guided tours through various languag-es. Unlike CodeSchool, each course or class is individually branded. For exam-ple, the jQuery class has an Airline/adventure feel, while the Objective-C classhas a retro videogame theme.

CHAPTER 2: Structured Sandbox

6

Try Redis

Try Redis! walks you through the redis database. The interface is purely textbased, making it feel a bilt like an old text adventure game, like Zork.

Try Redis

7

CHAPTER 2: Structured Sandbox

8

Unstructured sandbox

An unstructured sandbox provides an open ended, terminal-like model for en-tering and executing code. These terminals can be embedded inline in thepage, opened with a click of a button, or iframed into the structure of the over-all documents.

• Strengths

◦ Editorial flexibility — allows the author to insert whatever types ofcontent he or she will best describe the topic

• Weaknesses

◦ Design inflexibility. These often appear as iframes or something dis-ruptive to the overall experience.

◦ Non-integrated. Unless care is taken, the sandbox can feel like aneditorial afterthought.

Examples include:

repl.it

repl.it is a tool that uses various compiled languages (Python, Ruby, and Lua,among others). The site offers a code runner, an output pane, a surprisinglywide selection on languages, and a nice selection of samples for each type.

Unstructured sandbox

9

3

Programr

Programr runs languages in the browser including console (C++, C#, Java,Objective-C), web (PHP, Javascript, JQuery, Java Server Pages, AJAX), rich me-dia (Flex, Processing), desktop (Java Swing), and database (SQL, SQLite). Oth-ers on the site include Ruby, Python, VB, AJAX, Flex, Flash, iOS, Android, andmore.

Andrew’s analysis: “though it supports a pretty wide selection of languag-es, performance it pretty terrible. Like, check out these ruby examples:

http://www.programr.com/append-and-concatination http://www.programr.com/using-loop-1

They each take 9-10 seconds to evaluate.”

Twilio Pair Programming

http://www.twilio.com/blog/2013/06/pair-programming-in-the-browser-with-twilio.html

The tools for creating real-time applications in the browser are getting betterall the time. Running node.js on the server, in conjunction with libraries likesocket.io, makes it ridiculously simple to facilitate server push and event-drivencommunication between clients. Combine this with Twilio Client for voice com-

CHAPTER 3: Unstructured sandbox

10

munication in the browser and you have an incredibly powerful platform for fa-cilitating communication between users of your application.

Pair programming live with a distributed team is very much a possibility withsome of the technologies we’ll look at today. Let’s run through a list of ingredi-ents for this hack: * node.js on the server * The official twilio node module,available on npm * The Twilio Client JavaScript SDK (for the browser) * sock-et.io (both server and browser) * Express for routing HTTP requests and servingup responses * Ace code editor (browser) * AppFog (platform as a service forhosting)

iPython Notebook

iPython Notebook is a tool for viewing python in the browser. The authorwrites in an integrated environment (the native format is JSON) that allowstext, equations, and live code. (The code executes on a remote server.) The out-put of the code is presented in a terminal style format. One of the other reallynice features is that it is simple to embed images, like those generated from nu-merical or scientific tools like numpy or scipy.

iPython Notebook

11

Khan Academy

Khan Academy provides a vast array of learning classes around basic computerscience. There are typically a video or animation for each step, after which thestudent is able to experiment with the code in the sandbox. The coding environ-ment is divided into a pane for listing and a pane for the output, where the stu-dent can see the result. (Currently, only Javascript-based languages seem to besupported.) The code environment also supports a “Save as a spin off” buttonwhere the user can save the code listing to his or her own private account formodification.

Scratch

Scratch is an interactive learning environment geared towards kids. The useredits code in an IDE-like window. Tips, instructions, and tutorials can be appearin a sidepanel called “Tips” that can be turned on or off. The user can also savetheir programs (which are often like small animations or movies) so that theycan be shared.

CHAPTER 3: Unstructured sandbox

12

JQFundamentals

jqfundamentalsis a site for teaching javascript. It walks through a rich set ofconcepts that are illustrated with specific code examples. You can click on asmall icon on the example to open a live code editor where you can run the ex-ample.

JQFundamentals

13

Chimera

O’Reilly Chimera is a new beta site for experimenting with how books can be-come more interactive. At it’s current start of development, the site has embed-ded JSBins that allow the reader to try out the code. (Javascript only.)

CHAPTER 3: Unstructured sandbox

14

Opal

Opal is a ruby to javascript compiler. It is source-to-source, making it fast as aruntime. Opal includes a compiler (which can be run in any browser), a coreliband runtime implementation. The corelib/runtime is also very small (10.8kbgzipped).

Opal

15

try clojure

Try Clojure is an online sandbox for using Clojure, a dynamic programming lan-guage that targets the Java Virtual Machine (and the CLR, and JavaScript). It isdesigned to be a general-purpose language, combining the approachability andinteractive development of a scripting language with an efficient and robust in-frastructure for multithreaded programming.

CHAPTER 3: Unstructured sandbox

16

forio julia tutorial

Julia Tutorial is an interactive tutorial for the julia language. It’s sturcuted as acommand-line style tutoral, where the user can tye commands like “tutorial” or“next” that prompt you to try specific elements of the language.

forio julia tutorial

17

CHAPTER 3: Unstructured sandbox

18

Projects

This chapter contains interesting projects that illustrate patterns described inprior chapters and show interesting examples of new ways people are learningto code. (Versus using a plain old book or reference website.) If you find a newproject, add it here and try to note what is interesting about it, and which (ifany) of the patterns it uses.

Coderpad

CoderPad is a structured sandbox that allows two people to share screens(presumably, a interviewer and a job candidate.) It’s built using jsrepl, whichpowers a few other sites, like udemy and (I think, at least in an earlier incarna-tion) codecademy.

Projects

19

4

gamingjs

gamingjs is sandbox-like code editor that accompanies a book published bythe Prags. We don’t know a lot about this yet. It uses the Ace Editor.

CHAPTER 4: Projects

20

Nature of Code

Nature of Code is Dan Shiffman’s interactive book on modeling natural sys-tems in Processing. It’s got a number of really cool features:

• Running processing sketches that are sourced in at build time

• An open github repo for contributors at shiffman/The-Nature-of-Code• An innovative payment system that allows you to set your own price

Nature of Code

21

pythonmonk

pythonmonk is a free, interactive tutorials to help you learn Python in yourbrowser. It uses an unstructured sandbox approach to guide you through aseries of lessons. It’s free.

CHAPTER 4: Projects

22

voxeljs

voxeljs is a javascript-based minecraft clone. It’s a wonderful, sprawling projectthat has a game player, creature creators, world editors, and project sharing.It’s not a documentation project so much as it is an example of an emergingapplication, but it’s so cool that we need to pay attention to.

voxeljs

23

Versal

Versal is in beta.Learning gadgets Beyond video. Beyond slide decks. Versal brings interactiv-

ity to online learning through customizable exercises called “gadgets.”Drag and drop gadgets – simulations, charts and so much more - right into

your course, no coding required.And if you do know how to code? Our JavaScript API will be available to de-

velopers soon. Sign up for an invite.Are you a JavaScript developer? Are you intrigued by how interactivity will

reinvent online learning?We’ll be opening up our gadget platform/APIs very soon, and we’re looking

for a handful of creative developers and early adopters. Sign up for an inviteand we’ll be in touch shortly.

http://readwrite.com/2013/07/09/online-learning-is-broken-and-versal-wants-to-fix-it#awesm=~obdPx1gvIfi1ek

CHAPTER 4: Projects

24

Code Analysis and Metrics

This section covers services that evaluate a code repo and create ancillary ma-terial for it. For example, a service might compute various metrics (code cover-age for a test suite, etc), project management assets (for example, it sends amessage to a chat service when someone commits), documentation (rebuildsautomated docs on each commit), or other software engineering-related items.

The tools are often implemented as webhooks within a CI server (Jenkins,etc) or in the underlying version control system. These services can either befree or paid. If they’re paid, they’re typically implemented by having the userregister for a paid service and enter some sort of authorization token into theweb hook. ?, for example, shows how paid service is configured in GitHub’s“Service Hooks.”

Examples of metrics include:

25

5

CodeClimate

CodeClimate provides automated Ruby code review. You give it a repo by(among other ways) creating a GitHub service hook, and it will give you backsome reports. It’s a paid service with a tiered pricing scheme.

Documentation Generators

This section covers tools that build documentation directly from the sourcecode itself. This idea, called literate programming, was invented by DonaldKnuth as a way to create self-documenting programs. The technique is used bymany languages to create reference and API documents and sites.

Key tools include:

• Sphinx. Documentation generator for Python.

• JavaDocs. Documentation for Java.

CHAPTER 5: Code Analysis and Metrics

26

Code Evolution

Examples in this category show how code evolves over time. For example, youmight break a complex example down into a series of steps. At each changepoint, you show how the code progresses between steps.

Text-Based Description

This is the standard tech book approach — have a narrative series of listing thatshows the code at each point, and describe the changes between each.

Meteor Book

The Meteor Book has a nice system that uses commits at each checkpoint sothat the user can check out the code that corresponds to a specific section ofthe example. The nice thing about this method is that it allows the author makechanges in a natural way that is similar to how they would work with code.

27

6

Learn.js

Seth Vincent: Of note: Check out the pricing packages and \$10/month sub-scription.

_ I’m using semantic versioning for my book about javascript: Every techni-cal book should do the same._ https://medium.com/i-m-h-o/2aa5cff10010

\$29: The Book Pack * pdf, epub, and mobi versions of Learn.js. * 30 minutesof one-on-one javascript tutoring.

\$89: The Super Bonus Pack * pdf, epub, and mobi versions of Learn.js. * 2hours of one-on-one javascript tutoring. * Screencasts of the chapters as theyare produced.

The book: http://learnjs.io/

CHAPTER 6: Code Evolution

28

Modeling Execution and Flow

These sites reveal the flow and state of a program to deepen our understand-ing.

Learnable Programming

Learnable Programming is a Bret Victor essay about coding environments.One of its key points is that you should be able to see the progression of codestate across time as the program executes. So, if you have a variable, you mighthave a timeline that shows how the value changes on each iteration. It’s notclear from the essay if there is an actual editor of IDE he proposes, or if theseare concepts.

Jeff Atwood also has a great article on Victor’s ideas called Visualizing Codeto Fail Faster.

29

7

Deprocess

Deprocess is Ben Fry’s visualization of a program flow. It’s mostly an art piece,but it’s an interesting way to think about how you’d watch code change as itruns.

CHAPTER 7: Modeling Execution and Flow

30

Finding and Searching

GitHub Code Search

GitHub Advanced Code Search allows users to search for specific program-ming languages, file extensions, and more.

Stack Overflow

This site describes itself as “a question and answer site for professional and en-thusiast programmers.”

31

8

Formatting and Annotation

This category covers the different ways that code is either formatted or annota-ted. This can take the form of color coding the syntax, or pulling out commentsto create new documentation. Examples include:

Syntax Highlighting

Pygments

Pygments is a post-processor that applies syntax highlighting for a wide rangeof languages. (Some 200+ are supported.) The key advantage is that it makescode more readable.

33

9

Opal

Opal is another highlighter. Dan Allen has taken an interest in this project andmay use it with asciidoctor.

Docco

Docco is a Jeremy Ashkenas project that takes comments embedded in sourcecode and turns them into annotations that appear on the sidepanel of the list-ing. This allows the reader to more easily scan the code and read the commentsin a way that is visually more appealing than having the comments appearpurely inline.

Ace Editor

The Ace Editor is a text editor built in the style of textmate or sublime. It has anumber of useful features, like syntax highlighting (around 15 languages), linenumbering, a rich API, and a robust set of themes. A number of sites use it toshow listings, even if all you can do is copy the code from the box.

CHAPTER 9: Formatting and Annotation

34

35

Sharing

The sharing category covers different ways that people share code to others(duh!). They can range from simple (like posting something on a blog) to com-plex, but the basic idea is that these are ways people send out snippets or fullworked examples and get feedback.

Blogging / Static site

This is probably the classic method for sharing ideas about code, but it’s worthmentioning: simply blogging about it. There are a lot of great developers (BretVictor, etc) who write beautifully about development. Many of the tools men-tioned here are designed to complement blogging in one way or the other.

GitHub

GitHub is a site for sharing entire code repositories. Unlike some of the othertools mentioned here, which are more around sharing snippets or small exam-ples, github is used to host the entire codebase for a project. in addition tohosting the git repos, it also handles collaborators, issues, wikis, forking, pullrequests, and all the other elements required to run an open source project.

Sharing

37

10

JSBin

JSBin (and the similar site, JSFiddle) allow you to create snippets of Java-script, HTML, CSS, and a live preview that shows the output. Once you createyour snippet, you can then embed onto other sites. Think of it as a sort of You-Tube for Javascript. The viewer has the option to copy it into their own accountand make changes, as well. This has become a useful tool in the JavaScriptcommunity for sharing prototypes and ideas.

CHAPTER 10: Sharing

38

Gists / pastebin

gist and pastebin are services for sharing snippets of code or text. (Some peo-ple even write whole essays with them.) Once you create the snippet, you canget an embed code that you can use to embed the code onto a blog or othersite. People can then copy the gist to their own account so that they can modifyit.

Gists / pastebin

39

Post suggestions or comments here.

CHAPTER 10: Sharing

40