Documentation as Conversation with CSS

I love to explore new ways of conveying technical information, and I’m interested in documentation as conversation. Last year I wanted to convey a “side note” on each page of a Sphinx site, as if the page were talking to you. I needed to let people know that there are additional documentation pages available. So, I went looking for a CSS design that would let me put the note into a particular tag and style as I like. I found it at Pure CSS speech bubbles. The humorous part was figuring out what speech bubbles are also called so I could do a Google search. Speech balloons? Dialog balloons? Word balloons? I never did come up with balloon but somehow found bubble.

For Sphinx sites, which are built from RST (ReStructuredText), you use a layout.html file in a _theme folder with your .rst source files. This templating is explained in more detail on the Sphinx documentation site at http://sphinx-doc.org/. In this case, the p tag is styled with css classes. Here’s what the HTML looks like:

The CSS is much more involved, giving borders and rounded edges and putting that little triangle to indicate the speech. You can see it embedded in the Sphinx framework at tweaks.css. You can select a border color to match the rest of your page. Here’s the resulting HTML output.

You may have seen the trend towards comic books or comics to explain technical topics, such as the one for Google Chrome at http://www.google.com/googlebooks/chrome/. There are drawn comic characters explaining the browser design considerations throughout, with speech bubbles, hand waving, folded arms, lots of body language expressed throughout. This simple side bar doesn’t attempt that level of engaging content, but it’s a playful way to let people know there’s more than a single page for OpenStack docs. What do you think about such techniques, are they playful and harmless or sloppy and annoying?

9 Comments

I like it! The internet has conditioned all of us to be “scanners” rather than “readers” and this creative method is just far enough outside of the “normal” flow of content that it stands a chance of stopping scanning eyes. But it isn’t too intrusive.

Intriguing idea, Anne. I like the idea of the balloons. My initial concern is that using a CSS solution might make any other media deliverables akin to second-class citizens–only because the HTML is the one with the great callouts.

As with so many other things, it depends on the audience and (to borrow Kai Weber’s term) their mental model. For many, many tech comm projects — including open-source software and most consumer products — I think the comics approach is great. These audiences enjoy comics, and they understand that comics aren’t just about play.

Some audiences might find comics to be frivolous, or they might think that comics trivialize the subject. For those audiences we should stick to a more conventional approach. But for everyone else, this approach is likely to be very popular. You had a great idea, Anne, and it looks like you executed it beautifully.

Good point Scot about creating a first-class citizen in HTML-land… since Sphinx’s PDF output isn’t implemented there’s no other citizen in this case, but it’s a good point.

Carrie, I identify in that I don’t read comics much, never have. Then again, I am too impatient to watch videos when I could read instead. Then again, one great visual novel I read recently was Wonderstruck, wow, what a book. http://www.wonderstruckthebook.com/ Okay, too many then agains.