Sharing knowledge on the web

Joe Gregorio posted a gem the other day. It’s a little tutorial on how to model a common operation on the web — validating zipcodes — using the principles of the REST architectural style. Along the way, almost certainly without intending to, he taught me some things about the Python programming language that I hadn’t known.

Joe’s example uses two features of Python — memory-mapped files and array bisection — to speed up the search for a zipcode in a sorted file of zipcodes. But you don’t need to know anything about REST or Python to appreciate the aspect of Joe’s example I want to highlight here, which is that when we narrate our work on the web, we may convey more value than we know or intend.

The purpose of Joe’s posting was to show how to apply a recipe for RESTful design, and it accomplishes that nicely. In doing so, Joe is helping to articulate principles that are widely practiced but not always well understood. By reflecting on his knowledge of those principles, by writing them down, and by sharing that writing, Joe makes that knowledge available to the rest of us.

Along the way, other useful things happen. In the dialectic that emerges in the comments section, Richard Searle proposes — and Joe agrees — that the word originally chosen to invoke the validator, lookup, is too verb-like. The recipe calls for nouns, and so the word becomes zipcode instead.

Why did Joe choose lookup initially? Knowledge is imperfect. When we externalize what we know, we can observe and discuss and correct those imperfections. That’s one of the subtle benefits that flow from externalizing knowledge in public performance.

Another is the one I’ve already mentioned. Although I doubt Joe meant to teach me about memory-mapped files and array bisection in Python, he did anyway, as a happy side effect.

When the blogosphere works this way, as it often does, it exemplifies the best qualities of professional discourse. I wish I could show more people how this works. But it’s hard to abstract away from the knowledge domain of this example — RESTful design and Python programming — to general principles that can apply in any knowledge domain.

In the technical blogosphere, we have an almost perfect confluence of factors. Almost everything related to the work of software development — both products (source code) and processes (specifications, conversations) — is a text document that can flow easily and naturally on the web. And our examples are often self-reflexive — we use the web to illustrate work that is about the web itself.

This way of externalizing knowledge in public performance doesn’t translate so easily to other domains, at least not yet. I think that’ll change, though, as all work products and work processes tend toward digital representations. And I think that rich media will play a huge role in that change. Programming is fundamentally a textual craft, as are others, but many are not. If you’re a builder or a firefighter or a pilot, the most effective medium in which to publicly perform your knowledge won’t be text, it’ll be video.

Suppose you’re a builder, firefighter, or pilot who wants to share (and clarify) your knowledge of green construction, rescue operations, or cockpit instrumentation. It’s admittedly a stretch to imagine that, just as Joe Gregorio posted a textual blog entry in order share his knowledge of RESTful design, you’ll post a video in order to to share your knowledge in these areas. But I hope you will imagine it.

Posted in .

2 thoughts on “Sharing knowledge on the web

  1. Jon writes that Joe Gregorio’s article articulates “principles that are widely practiced but not always well understood.”

    That’s definitely the state of things for RESTful systems; in contrast with SOAP, WSDL, and the rest of the protocols in the W3C’s Web Services stack, RESTful principles are closer to folklore thanto a formal set of committee-developed specs. That’s changing now, in part due to contributions like Joe’s wonderful article series on REST, and also due to a forthcoming book from O’Reilly, RESTful Web Services by Leonard Richardson and Sam Ruby, at These and other writings are attempting to provide at least a normative set of best practices for use in building services based on the REST paradigm.

Leave a Reply