Many software projects enforce mandatory code reviews, even for their most senior developers. While I’ve mentioned before that code reviews can be very useful, I also think that mandatory code reviews among trusted members of a software team can have a number of downsides.

First and foremost, developers don’t have a common consensus on what code review actually means. How much time should it take? Does it mean acting like a human computer and painstakingly processing every line of code like a computer would? Does it mean evaluating the high-level architecture of a patch, or finding formatting errors? Does it mean just skimming the code and vaguely understanding it enough to take care of it if the original author gets hit by a bus? Does it mean evaluating the big-O complexity of an algorithm? Does it mean all of these things?

Many people who ask for mandatory code reviews have no idea what they’re asking for—because it’s mandatory, so they just have to—and the people who do the code reviews are in a similar position. As a result, while code reviews often improve software quality, in some environments a mandatory review policy can amount to an ill-defined bureaucratic ritual of unknown value.

Because of this, I’ve seen a lot of reviewers—myself included—offer nothing but so-called “nitpicks” in their code review comments, as a way of appearing to perform a useful act while in fact slowing a project down, destroying morale, and optimizing for their own minimal time investment by engaging in days or weeks of asynchronous pedantry. Other times, because reviewers have been asked to do something extremely vague, they often procrastinate, which causes code to bit-rot and sets a project back even further.

But what happens when we make code reviews voluntary, instead of mandatory? Well, then it’s called asking for advice.

Many of the most useful “code reviews” I’ve experienced came not from asking someone’s permission to land code, but from simply being uncertain of very specific aspects of my own code, and asking my peers for help. Sometimes this has come in the form of a github pull request; other times it’s been in the form of pair programming; other times it’s just involved me dumping some source code into a webpage and asking someone over IRC about it.

There are a number of things I like about this practice. The first is that it’s my choice to ask for advice, which is far more empowering than asking for permission, which is what a mandatory code review policy implies. Even if I had the exact same conversations through mandatory code reviews that I would through voluntary code reviews, I would still enjoy the latter more, because they’re my decision rather than my obligation.

Another advantage of voluntary code reviews is that I know exactly what I’m asking for. If I feel insecure about my own code, I can introspect and understand why I’m feeling that way, which leads me to specific questions. Often different questions are best answered by different people, some of whom may even work on different projects; when I ask those people to review my code, I’m requesting very specific things that are highly relevant to their expertise. I’m also targeting my questions in a way that ensures that I don’t take up too much of their time. And because it’s viewed by them as a well-defined, time-boxed favor rather than a vague obligation, they’re typically much more responsive and excited about helping me than they would be if it were a mandatory code review.

In conclusion, rather than decreasing software quality, I believe that the social incentives inherent in voluntary code review policies encourage developers to take ownership of the code they write by paying close attention to its needs and valuing the time of others who may need to take a look at it.

Recently the Twitter Bootstrap documentation gave a name to something that I’ve been excited about for a pretty long time: Markup API.

Markup APIs give superpowers to HTML. Through the use of class attributes, data attributes, X-Tags, or other conventions they effectively extend the behavior of HTML, turning it into a kind of magic ink. Favorite examples of mine include Twitter Bootstrap, Wowhead Tooltips, and my own Instapoppin.

The advantages of a markup API over a JavaScript API are numerous:

• They mean that an author only needs to know HTML, whose syntax is very easy to learn, rather than JavaScript, whose syntax is comparatively difficult to learn.
• Because the API is in HTML rather than JavaScript, it’s declarative rather than imperative. This makes it much easier for development tools to intuit what a user is trying to do—by virtue of a user specifying what they want rather than how to do it. And when a development tool has a clearer idea of what the user wants, it can offer more useful context-sensitive help or error messaging.
• Because of HTML’s simple and declarative structure, it’s easy for tools to modify hand-written HTML, especially with a library like Slowparse, which help ensure that whitespace and other formatting is preserved. Doing the same with JavaScript, while possible with libraries like esprima, can be difficult because the language is so complex and dynamic.

These advantages make it possible to create GUI affordances atop hand-coded HTML that make it much easier to write. As an example of this, I hacked up prototype slideshow demo and physics demo in July of last year. Dragging an element with the class thimble-movable in the preview pane changes (or adds) CSS absolute positioning properties in the source code pane in real-time, and holding down the shift key modifies width and height. This allows users to size and position elements in a way that even a professional developer would find far more preferable to the usual “guess a number and see how it looks” method. Yet this mechanism still places primacy on the original source code; the GUI is simply a humane interface to change it.

This is the reverse of most authoring tools with an “export to HTML” feature, whereby an opaque internal data model is compiled into a blob of HTML, CSS, and JavaScript that can’t be re-imported into the authoring tool. Pedagogically, this is unfortunate because it means that there’s a high cost to ever leaving the authoring tool—effectively making the authoring tool its own kind of “walled garden”. Such applications could greatly facilitate the learning of HTML and CSS by defining a markup API for their content and allowing end-users to effortlessly switch between hand-coding HTML/CSS and using a graphical user interface that does it for them.

Much has been said about the greatness of the Web, yet most websites don’t actually work like the Web does. And some experiences that aren’t even on the web can still embody its spirit better than the average site.

Here are three webbish characteristics that I want to see in every site I use, and which I try my best to implement in anything I build.

• “View Source” for every piece of user-generated content. Many sites that support user comments allow users to use some kind of markup language to format their responses. Flickr allows some HTML with shortcuts for embedding other photos, user avatars, and photo sets; Github permits a delicious smorgasboard of HTML and Markdown.

  The more powerful a site’s language for content creation, the more likely it is that one user will see another’s content and ask, “how did they do that?”. If sites like Flickr and Github added a tiny “view source” button next to every comment, it would become much easier for users to create great things and learn from one another.

  I should note that by “source” I don’t necessarily mean plain-text source code: content created by Popcorn Maker, for instance, supports a non-textual view-source by making it easy for any user to transition from viewing a video to deconstructing and remixing it.

• Outbound Linkability. Every piece of user-generated content should be capable of “pointing at” other things in the world, preferably in a variety of ways that support multiple modes of expression. For instance, a commenting system should at the very least make it trivially easy to insert a clickable hyperlink into a comment; one step better is to allow a user to link particular words to a URL, as with the <a> tag in HTML. Even better is to allow users to embed the content directly into their own content, as with the <img> and <iframe> tags.

• Inbound Linkability. Conversely, any piece of user-generated content should be capable of being “pointed at” from anywhere else in the world. At the very least, this means permalinks for every piece of content, such as a user comment. Even better is making every piece of content embeddable, so that other places in the world can frame your content in different contexts.

As far as I know, the primary reason most sites don’t implement some of these features is due to security concerns. For example, a naïve implementation of outbound linkability would leave itself open to link farming, while allowing anyone to embed any page on your site in an <iframe> could make you vulnerable to clickjacking. Most sites “play it safe” by simply disallowing such things; while this is perfectly understandable, it is also unfortunate, as they disinherit much of what makes the Web such a generative medium.

I’ve learned a lot about how to mitigate some of these attacks while working through the security model for Thimble, and I’m beginning to think that it might be useful to document some of this thinking so it’s easier for people to create things that work more like the Web. If you think this is a good (or bad) idea, feel free to tweet @toolness.

Marco Zehe recently wrote a good, sobering blog post comparing the accessibility of Web apps to those of native ones.

Much of what I’ve seen on supporting accessibility on the Web has to do with using the right standards: always providing alt attributes for images, for example, or adding semantic ARIA metadata to one’s markup.

As a designer, however, I don’t have much interest in these standards because they don’t seem to address human factors. What’s more interesting to me is understanding how screen readers present the user interface to vision-impaired people and how usable that interface is to them. This would parallel my own experience of designing for non-impaired users, where I use my understanding of human-computer interaction to create interfaces from first principles.

I’ve been meaning to actually get a screen reader and try browsing the Web for a few days to get a better idea of how to build usable interfaces, but I haven’t gotten around to it yet, and I’m also not sure if it’s the best way to empathize with vision-impaired users. In any case, though, my general concern is that there seems to be a distinct lack of material on “how to build truly usable web applications for the vision impaired.” Instead, I only see articles on how to be ARIA standards-compliant, which tells me nothing about the actual human factors involved in designing for accessibility.

So, I’ll be spending some time looking for such resources, and trying to get a better idea of what it’s like to use the internet as someone who is vision-impaired. If you know of any good pointers, please feel free to tweet at me. Thanks!

HTML is a very interesting machine language because, like human languages, most things that interpret it are very forgiving.

For instance, did you know that the following HTML is technically invalid?

<video>
  <source src="movie.mp4"></source>
</video>

It’s invalid because <source> is a so-called void element: since it can’t have any content inside it, you simply don’t need a closing tag for it. The <img> tag works the same way. The technically correct way to write the above HTML snippet is as follows:

<video>
  <source src="movie.mp4">
</video>

However, in practice, all Web browsers will interpret both of these snippets the exact same way. When a browser sees the closing </source> tag on the first snippet, it realizes the “mistake” the author has made, and simply pretends it isn’t there.

What’s interesting to me is the way this mirrors human languages, and what it means for teaching. For instance, the following sentence is grammatically incorrect:

The dog loves it's owner.

However, no one who knows English will actually be confused by the meaning of the statement.

When I was trained as an adult literacy tutor several years ago, one of the most important principles we were taught was that fostering a love for writing was vastly more important than grammatical correctness. The “red pen” commonly used by school teachers for correcting grammatical errors was seen as anathema to this: when we found a grammatical error in a novice writer’s work, we were encouraged to ignore it unless it actually made the piece confusing or ambiguous for readers in a way that the author didn’t intend. Otherwise, the novice writer would become quickly distracted and discouraged by all their “mistakes” and view writing as a minefield rather than a way to communicate their thoughts and ideas.

We’re running into similar issues in the design of the Webpage Maker. On one hand, the fact that Web browsers are so forgiving when interpreting HTML enables us to follow a similar philosophy as that of progressive adult literacy tutors.

But sometimes, the forgiving nature of Web browsers backfires: they actually render a document that is vastly different from the author’s intent, which is just as frustrating as a pedantic nitpicker. We’ve created a library called Slowparse—soon to be renamed—which attempts to assist with this, providing the logic needed for a user interface to gently inform users of potential ways their HTML and CSS code might be misinterpreted by machines. A full specification of errors and warnings is also available, as is an interactive demo that uses the library to provide real-time feedback to users.

It’s been interesting to see how different Slowparse is from a HTML/CSS validator, whose goal is not one of learning, but of ensuring conformance to a specification. From a learning perspective, a validator is like the pedantic teacher who loves their red pen: some of its feedback is quite useful, but the remainder is likely to confuse and intimidate a newcomer.

Partly as a result of its learning goals, Slowparse actually “warns” the user of things that are technically valid HTML/CSS, but which likely don’t reflect the intent of the author. One current example of this is in regards to the use of unquoted attributes in HTML5, though that particular example is still subject to change.

At this point, I think the challenge will be to work with our learning team and user test our interface to the point that we achieve a good balance between being a pedantic nitpicker and providing useful feedback that helps users as quickly as possible. In my opinion, if we do things right, we’ll help people develop a love for HTML and CSS—even if what they write may technically be “grammatically incorrect.”

Presentations take a long time to make. Particularly when I’m just conceptualizing my presentation, it takes a lot of work to record myself talking, use a tool to sync it with the proper visuals, and then repeat the recording and syncing process as I iterate on the content.

I recently made a simple tool called Quickpreso to make the process of “prototyping” a presentation quicker, and more like writing a simple HTML page.

A presentation in Quickpreso is just an HTML file with a series of alternating lines for visuals and voice-overs, like this:

<img src="slide-one.jpg">

This text will be spoken for slide one.

<a href="http://mozilla.org/">I am slide two.</a>

This text will be spoken for slide two.

The visuals can contain any HTML markup. Each section of voice-over text is rendered by the OS X say command; they’re all concatenated together into an audio file by ffmpeg. Finally, the visuals are synced to the audio in a Web page using popcorn.js.

Quick iteration is facilitated by a simple Python web server that regenerates the audio file when it detects changes to the voice over text. The final product is all static content that can be served from any web server.

I used this tool to create a Webmaking for Knitters presentation in January. The result is quite robotic, obviously, though it can be made a little more natural-sounding if newer voices from OS X Lion are used (I’m still on Snow Leopard).

One particular advantage of this approach, however, is that you get subtitles/closed-captioning for free. There’s also nothing preventing you from re-recording the final audio in your own voice once you’re happy with your prototype.

The source code is available on Github at toolness/quickpreso. The code is in an alpha state, so your mileage may vary; fortunately, though, the source code is miniscule, so understanding and changing it shouldn’t be hard.

Last week I merged the Webmaking Tutorial Prototype with the Webmaking 101 for Journalists prototype we made during our three day sprint in NYC in February.

The result, which is code-named Storything, is currently hosted at storything.toolness.org. Give it a try!

The design for this prototype is based on Jess Klein’s instructional overlay mockups. A separate two-pane editor for example snippets is included in the movie frame; my hope here is that by setting the tutorial movies in an actual editing environment, users will obtain a better understanding of how to use our tool. This is further aided by the ability for the tutorial movies to highlight parts of the user interface outside the movie frame.

At present, the prototype awards badges for a few simple things, like creating your first paragraph and header elements. These badges aren’t necessary to advance the tutorial, however; this is partly because we’d like the tutorial to be approached in a non-linear way, and also because the assessment algorithms for the badges likely can’t capture every possible edge case in user input.

The prototype’s source code can be forked at toolness/storything on Github.

Recently I’ve been playing around with creating interactive tutorials that teach people how to create things on the Web.

Check out this prototype. At the end of a movie-like tutorial, you’ll be given a challenge to write your first bit of HTML. At any time, you can use the scrubber at the bottom-right to review any part of the tutorial; anything you’ve typed so far in the challenge is undone while you’re scrubbing, and is automatically re-applied once you’re back at the challenge.

This prototype is an evolution of an idea that Jess Klein wrote about regarding instructional overlays for our webmaking tools.

How It Works

The tutorial uses Popcorn to construct a “movie” that automates the user interface of a two-paned HTML editor with an instructional overlay. I made an ad hoc mini-framework called tutorial.js to make it easy to script these sorts of experiences; for example, here’s what the beginning of the prototype’s tutorial looks like:

Tutorial
  .dialogue("Hi! I am Mr. Love Bomb and will teach you how to be a webmaker now.", 0)
  .typechars("you're really cool.")
  .dialogue("Check it out, this is HTML source code—the language of the Web.", 0)
  .spotlight("#editor")

The dialogue() method just makes the tutorial avatar—in this case, Mr. Lovebomb—say something. typechars() types some characters into the HTML editor, and spotlight() draws the user’s attention to part of the page. Each action is queued to occur serially, in a style inspired by the chaining API of soda.

The full tutorial script is at tutorial-script.js, and the full tutorial source is available on Github.

I recently made The Parable of The Hackasaurus, which is a game-like attempt to make web-hacking easy to learn through a series of simple puzzles in the context of a story.

The parable is really more of a proof-of-concept that combines a bunch of different ideas than an actual attempt at interactive narrative, though. The puzzles don’t actually have anything to do with the story, for instance. But I wanted an excuse to do something fun with the vibrant art that Jessica Klein has made for the project, while also exploring possibilities for the Hack This Game sprint and giving self-directed learners a path to understanding how the Hackasaurus tools work.

If you know HTML and CSS, you’re welcome to remix this and make your own “web hacking puzzle” where the goggles are the controller. Just fork the repository on GitHub and modify index.html and bugs.js as you see fit. Almost all the puzzles, achievements, and hints are data-driven and explained in documentation, so you don’t actually need to know much JavaScript.

For more information on my motivations in creating the parable, check out the experiment’s README. Jess is also thinking about making an interactive comic that teaches web-hacking, which I’m looking forward to.

As I mentioned at the end of my last post, there’s a lot of usability problems that make writing an offline web app difficult.

When writing a “native” client-side app using technologies like Microsoft .NET or Apple’s Cocoa framework, it’s assumed that everything your program is doing, and everything it needs, is already installed on the local device. Anything not on the local device needs to be explicitly fetched over the network. Any app is therefore “offline” by default, and it’s very easy to tell, both when reading and writing code, when it needs to access the network.

Understandably, this makes it trivially easy to write an offline native app. One’s very first app works offline, unless there’s something related to the app’s purpose for which network access is obviously required.

On the other hand, offline web apps build on the already confusing, frequently opaque world of resource caching. They also break developer expectations in various ways that I’ll explain shortly. Furthermore, no browsers except Chrome provide tools for introspecting and understanding the behavior of an offline application, which adds to developer frustration.

Problem One: Simple Things Aren’t Simple.

Let’s say you’ve made a simple web-based currency converter, which is fully self-contained in a single HTML file and never requests any resources from the network. A browser won’t let it be accessed while the user is offline unless you do a few extra things:

1. Create a manifest which enumerates every resource that needs to be available to the app.

2. Make sure the manifest is served with a mime type of text/cache-manifest, which is done differently depending on the web server software you’re using.

   As I mention in my post On The Webbyness Of An Installable Web App, this single requirement vastly complicates the scope of the problem by requiring developers to understand the HTTP protocol layer and their web server software. Furthermore, Chrome’s Web Inspector also appears to be the only tool that provides helpful error feedback if the manifest is of the wrong type—developers using Safari, Opera, or Firefox will likely be confused as their application silently fails to be cached.

3. Add a manifest attribute to their HTML file’s <html> element that points to the manifest.

Doing all this will allow you to deploy your simple currency converter app for offline use; it’s clearly much harder than writing an offline native app. But what’s worse is that adding offline support complicates further development of your app in a number of ways.

Problem Two: Your Development Workflow Is Now Broken.

Let’s say you make a simple typo fix in your HTML file. The fix won’t actually propagate unless you also alter your app’s manifest file in some trivial way; even then, because the cache manifest is checked after the cached version is loaded, the page needs to be reloaded an additional time to activate the new version.

Needless to say, this complicates the development workflow for the app, as it impacts the edit-test cycle. Workarounds exist, of course; for All My Etherpads, I’ve added an --ignore-cache-manifests option to the bundled Python development server that allows the server to pretend that the manifest doesn’t exist, so that the app’s offline cache is obsoleted and code changes propagate instantly. Even though such workarounds make it possible to develop as one normally does, developers still must remember to make a trivial change to their manifest file when they re-deploy, or else their existing users won’t see their changes.

Problem Three: Your App Can’t Access The Network When Online.

After creating your first completely offline app, you might think that adding a manifest file would just let you specify what files your app needs for offline use, and that accessing other resources would obey the normal rules of the web: they’d be accessible if the user happened to be online, and they’d fail to load if the user was offline.

But this isn’t the case at all. Simply having a manifest file changes the rules by which a page accesses any network resource, whether the user’s browser is online or offline. Unless a manifest explicitly lists a resource in one of its sections or contains an asterisk in its NETWORK section, attempting to access the resource from an XMLHttpRequest, a src attribute in a HTML tag, or anything else will fail, even if the user is online. No browsers currently provide very good feedback about this, either, leaving developers befuddled.

Problem Four: Cross-Browser Support Is Hard.

Not all browsers support the full application cache standard. Some browsers, for instance, don’t support the FALLBACK manifest category, which will cause apps on those browsers to behave differently.

Problem Five: There’s Not Much Tooling For This.

As I mentioned at the beginning of the post, Chrome is the only major browser that provides any information on the state of the application cache. Developers on other browsers at least need to add some code that monitors the state of the application cache and logs the many kinds of events it can emit, but even that information doesn’t tell you everything you need to know.

This is probably the most important problem, since it exacerbates all the others: if an offline app isn’t behaving as expected, a developer without the right tools can’t tell whether it’s due to many of the problems explained above, or something else entirely.

The Bigger Picture

These issues are symptomatic of a larger problem that most in-browser development tools face, which is that they generally provide little information that tells you exactly why a resource couldn’t be accessed. Aside from the complexities offline apps introduce, cross-origin resource sharing and the single-origin limitations put upon fonts and video make resource access in HTML5 incredibly complex. Yet most of our tools haven’t yet adapted to the development problems that arise when we use the new platform features.

The Good News

One of the best things about offline web apps, which is part of the reason for the additional complexity from the world of native apps, is that automatically updating is simply part of the way they work; you don’t have to put them on an online marketplace to benefit from the functionality, nor do you have to research and invest in any kind of third-party libraries that incessantly nag the user to upgrade. This is awesome.

As for the challenges facing developer ergonomics, help is on the way. Mikeal Rogers and Max Ogden are currently working on a project to make offline web apps easier to build. Folks at Mozilla believe that support for offline apps is an important use-case and want to make the user and developer experience better. Every major browser except Internet Explorer already seems to support the feature, which is also great. I’m already thinking of a few ways to ease these hassles myself.

In the long term, though, as I explained in my previous post, I think that the user perception of offline web apps—and the associated usability problems with even using a browser offline—are at least as important as the developer-facing challenges. Fortunately, the Open Web has some really awesome advocates, and I’m confident we can solve all of these problems once we put our heads together.