Comic-Based Communication

These days, there are as many styles of documentation as there are of programming. Structured docs (waterfall model), topic-based writing (object-oriented development), less formal styles based around wikis (agile coding). Another one that I haven't seen given a name, is what I think of as comic-based communication.

If you grew up with comic books, fingers poised next to "continued on 3rd page", following the narrative jumping from panel to panel, then you probably don't have a problem understanding this style. Cinematic examples would be the first Hulk movie or the TV series 24, where the action sometimes splits into multiple frames that all run side by side for a few seconds.

I haven't found such presentation compelling in movies or TV. The origin story of comic-based communication is based around the printed page. So its heroic destiny probably lies with static images, either on paper or computer screen.

One buzz-worthy example is Google's overview of the Chrome browser. It was, ah, inked by well-known illustrator Scott McCloud. Scott's "Understanding Comics", "Reinventing Comics", and "Making Comics" are kind of the "Mythical Man Month" of the medium. (I could swear I read one of them, probably the last, all the way through on Scott's blog but I can't find it now.) Here's a talk from the 2005 TED conference with some history and examples. (Start at 7:43 to skip the biographical stuff.)

In the Google overview, we see a lot of principles that it's hard to do justice to in a blog post. There's Tuftean multi-dimensionality -- characters and dialog bubbles are positioned around or even interact with charts, symbols, and and bits of screen imagery from the Chrome UI. The "speakers" aren't intimidating because they look like cartoon characters. Their rotoscoped look also means we can't pick holes in their appearance. It someone looks geeky or sloppily dressed, hey that's just a mild caricature by the artist.

The overview touches on subjects that makes software companies nervous to address in documentation -- things are slow, they crash, they're insecure -- but illustrate those ideas with witty, exaggerated graphics. What competitor is going to cry foul, what customer is going to gripe, that you're slighting someone else's product or exaggerating your own merits? It's supposed to have a tinge of absurdity after all. This style could be used for conceptual information where you're just trying to impress certain points on people, and on troubleshooting information where you can exaggerate things that go wrong and responses to problems. I don't know if it would work as well for task or reference information. The presentation employs the same mnemonic tricks that good students use intuitively, to hook important facts and relationships to memorable images.

Every communication style needs its authoring and presentation tools. (Word, Powerpoint, Framemaker, Acrobat, Wiki, Wordpress, Firefox, and so on.) For authoring in comic style, there's the application Comic Life, for both OS X and Windows. You can put together a PDF, web presentation, various kinds of images, or Quicktime movie. You can lay out pages with various panels familiar from the comic book days, and place thought or speech balloons, letter boxes, and stylized logo/title text.

The essence of each panel is an image, which can be dragged, scaled, cropped and rotated. This presentation is fascinating to me, because I've spent so much time on traditional photography. In a typical photographic presentation, you need to pick the best pictures that are perfect in every detail; but don't use too many, because they'll be viewed one at a time, and your audience will get bored if pictures are too similar or the transitions are too fast or slow.





With a comic-style presentation, you only need to find an interesting section of the picture with the same general shape as the panel. It can be a narrow sliver or an irregular shape. The rest of the picture (which in real life might be overexposed or blurry) is left to the reader's imagination. Page layouts let you present similar pictures in the form of a narrative, so no need to pick a single best one. Or you can float foreground pictures over a background image, either with a similar theme or a stark contrast. Text presented as speech balloons or captions in a letterbox carries a different tone than bullet points on a Powerpoint slide; again, you can exaggerate, understate, and leave out details for the reader's imagination to fill in.

The examples on the right come from a trip through the Grand Canyon and Bryce and Zion national parks in Utah. It's been more than a year and I'm not nearly finished even a first pass through the pictures to put together a traditional slideshow. But with the slideshow reimagined as a comic book, new perspectives and narrative possibilities jump out.

You've Got to Fight for Your Invoker's Rights

This post is about a PL/SQL feature that doesn't get enough respect, "invoker's rights".

First off, what's its real name? Depending on the source, you'll see the feature name spelled "invoker's rights", "invokers' rights", or "invoker rights". That makes a difference -- you'll get different results in Google depending on what combination of singular, plural, and possessive you use. And to be strictly correct, shouldn't you hyphenate the adjective form, that is, refer to things like "invoker's-rights subprograms"? I'm not even going to go there. Although I personally call the whole feature "invoker's rights" to agree with the PL/SQL manual, I'll try to make it through the rest of the post without using that phrase at all.

After all that, the syntax for the feature is AUTHID CURRENT_USER. Although there is an opposite AUTHID DEFINER clause, since that's the default, you would probably only ever use the CURRENT_USER form of the clause. It might get more love (and be easier to search for) if we called them "CURRENT_USER subprograms" or some such.

The mechanics of this feature are relatively easy to see. You can find the details in the PL/SQL manual, or get a tutorial that points out some of the nuances, or this Steven Feuerstein article with some best practices.

But still, how does that play out in the real world?

Well, you may have a PL/SQL application that goes through several versions, with each version in a different schema on the same database server -- MYAPPV1, MYAPPV2, MYAPPV3, etc. Or maybe there are slightly different incarnations of the app for different business groups. When you make a fix or improvement to one procedure or function, if that change is applicable for the older or alternate versions, you need to recompile the procedure or function in each schema. If program units that needed periodic upgrades were put into a central schema and declared with AUTHID CURRENT_USER, making the change in one place would propagate the improvements to all versions of the application. You could hardcode the central schema name in all calls to the CURRENT_USER subprograms, or create synonyms and pretend they're in the same schema as the rest of the code.

The trick then would be to identify which procedures and functions are the best candidates for this treatment. Logically, they should be small simple subprograms that have relatively few dependencies, so they won't break if your application gains or loses tables, columns, or other subprograms as it evolves. They should also be subprograms that you could predict would be important to fix or upgrade in the future -- ones that could give a big speedup when you learn some tuning technique or use some feature in the latest database release; ones that implement security checks that you'll make more stringent as security practices evolve; ones that display common UI elements that you can make more usable and accessible over time.

Of course, this type of foresight is easier said than done. Sure, just take all your slowest, buggiest subprograms with the worst output, and separate them out. But you might be able to retrofit such changes at a reasonable point. I'd suggest evaluating whether you could make use of AUTHID CURRENT_USER around the time of the 3rd instance or version of the application on the same server.