Layouts for programming essays, take two

For a while now, I've been thinking about what an optimal layout for a programming essay would look like; an arrangement that would give both text and code listings the best usability.

The challenge gets more interesting when one considers responsiveness; you want your technical article to look its best on desktop, tablet, and smartphone screens.

I have a hard time identifying a technical website that gets it right. It's common to see code that breaks out of its container (because the former is set to absolute width); wrapping lines of code (because the latter is set to absolute width); and code that's in horizontal scrolling mode although there is plenty of whitespace available in the margins of the text column.

Iteration One

About a year ago, I released Literate Code, an experiment with a responsive programming essay, to address this problem. The idea was to use a left–aligned column of text, and float the code listings to the right of it. For tablet and smartphone modes, code would collapse into a single column together with the text.

While that experiment has been worthwhile, its approach suffers from several shortcomings; it's time to re–visit the problem.

First and foremost, any text–based layout must build on the measure — which is the width of the main column of text. When code is floating to the left of text, the priority isn't clear. Which is the main element: text or code? One could argue for both — they certainly both have weight.

Secondly, widths of code blocks are variable by nature. In programming, we have certain recommendations as to how long lines of code should be for best readability (some would say, no longer than 40 characters). In practice, lines of code easily get longer. Many factors come into play: the programming language in question (CSS, for one, can have very long lines of media queries); code comments; etc.

So the initial attempt at Literate Code failed to give code optimal space; space that would accommodate lines of code of arbitrary length.

Iteration Two

The latest iteration addresses this concern. After some thinking, I came to the conclusion that what's needed is a layout that:

  1. Uses a single column in all modes — desktop, tablet, smartphone.
  2. Allows blocks of code of variable widths.
  3. Does not wrap lines or enter into horizontal scrolling mode until absolutely necessary (i.e., until there's no more whitespace available).

On my desk, there's a book ("Now You See It" by Stephen Few), open on pages 32–33. Both pages have illustrations; on the left page, the image fits inside the main column. On the facing page, the image expands far into the whitespace to the right of the text. Alternating text and illustrations of variable widths is a common practice in book design.

Why isn't this method utilized more in web design? It's natural to use it today, as screens of different dimensions call for flexible layouts that allow us to take advantage of every piece of screen real estate. We still tend to let the width of the main column constrain what we put in it, rather than using it to divide the page into segments that we can work with further, and enhance.

So, here is Literate Code, iteration two. It's the template for this article. Text is left–aligned, to make space for extra long columns of code. Columns span the range of 8 to 12; my container is 12 columns wide, my measure 8 columns wide — so the columns span the interval between the two.

If you are a programmer reading technical essays, chances are this happens on a desktop / laptop screen most of the time. So the 80% of the user experience for this layout is the 20% (or so) desktop media query range. Although desktop experience is clearly the one to optimize for, "mobile first" still can teach us a lesson here about the universal applicability of a single–column layout.

Implementation details

My wrapper div spans 12 columns, is set to fixed width, and adapts column–by–column:

        .wrapper {
          width: 52.5em; /*12 col*/
          margin: 0 auto;
        @media screen and (min-width: 48em) and (max-width: 65.5em) {
          .wrapper {width: 48em; /*11 col*/}

Inside of this wrapper, columns are sized using percentages:

      .col8p  {width: 65.714285714%;} /*MEASURE*/
      .col9p  {width: 74.285714285%;}
      .col10p {width: 82.857142857%;}
      .col11p {width: 91.428571428%;}
      .col12p {width: 100%;}          /*WRAPPER = 100%*/

At 58.275 ems (tablet mode), all columns contained within the wrapper are set to 100%:

      @media screen and (max-width: 58.275em) {
        .col12p, .col11p, .col10p, .col9p, .col8p {width: 100%;}

Literate Code 2 will be hosted on GitHub once I extract it from this site.

Comments or suggestions?

Does this look like something you'd use? Let me know on Twitter.


The CSS for code blocks borrows some styles from the Prism syntax highliter, by Lea Verou.

Literate Code is a content type. The most effective websites use custom layout templates for the types of content they feature. Less effective ones cram all content into generic templates. To learn more about the relationship between design and content, check out my upcoming book, Successful Website DNA.