Documentation as Conversation with CSS

Three types of speech balloons: speech, thought, scream.

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 In this case, the p tag is styled with css classes. Here’s what the HTML looks like:

<p class="triangle-border right">
Psst... hey. You're reading the latest content, 
but it's for the Block Storage project only. 
You can read <a href="">
all OpenStack docs</a> too.</p>

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. Speech bubble example

You may have seen the trend towards comic books or comics to explain technical topics, such as the one for Google Chrome at 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?


  • Bob Beims
    May 23, 2013 - 7:13 am | Permalink

    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.

  • May 23, 2013 - 8:04 am | Permalink

    Why thank you Bob! Now that I look at it again I wonder if the triangle should be on the left, but I’m leaving it alone. 🙂

  • Carrie
    May 23, 2013 - 12:10 pm | Permalink

    It’s definitely an interesting idea. I like your adoption but found the Google “comic book” a bit tedious to read and look at. Could be because I’m not really into reading comics to begin with 🙂

    I think in addition to the “tip callout” you mention, it could be interesting to use these for FAQ or troubleshooting information.

  • May 23, 2013 - 3:11 pm | Permalink

    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.

    I need to think this over some more, but I like it.

  • May 24, 2013 - 3:39 pm | Permalink

    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.

  • June 1, 2013 - 8:29 pm | Permalink

    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. Okay, too many then agains.

  • June 4, 2013 - 4:57 pm | Permalink

    Hallo Anne

    What a great idea! It’s especially good that you can use CSS to draw the bubbles.

    This ties in nicely with a recent discussion in our team, about using decorated boxes such as information boxes, tips, warnings and notes. There’s some research that suggests people don’t read content in framed boxes:
    Banner blindness
    Fancy formatting ignored – looks like an ad

    But I’m thinking people are more likely to read content that’s in speech bubbles. We’re even conditioned to do that, these days.


  • Pingback: Banner blindness and technical documentation | ffeathers

  • June 25, 2013 - 10:06 am | Permalink

    If you medium is the web and HTML, it’s awesome. I’d say go for it; after all, let’s not forget that HTML was originally designed for documents/documentation!

    Oh; it’s not “comic books”, they’re “graphic novels”. 🙂

  • Leave a Reply