Monthly Archives: June 2015

Include Code Samples in Markdown Files

angelfish.jpg

Introduction

One useful feature that Markdown omits is any way to properly maintain formatted code samples in the text. Instead you have to indent your code samples “by hand”. This is easy to mess up, especially if you have a team of people all editing the same files.

Code indentation and formatting is an important issue if you are writing tech docs intended for engineers. It’s mostly about ease of readability. Badly formatted code is jarring to the eye of your reader and makes the rest of your documentation seem instantly suspect.

In this post I’ll share a technique (a script, really) that I’ve developed for “including” longer code samples into your Markdown documents from external files 1.

Motivation

To understand the motivation for this technique, let’s look at some made-up code samples. If you already understand why one might want to do this, feel free to skip down to the code.

First up is the simple case: a code snippet that’s just a few lines long.

# Spaceship docking mechanism.

my $foo = Foo->new;
$foo->rotate(90);
$foo->engage_maglocks;

That wasn’t too bad. However, you may need a longer code sample like the one shown below which uses a lot of indentation. You really don’t want to be manually indenting this inside a Markdown file.

;; Ye Olde Merge Sort.

(define (merge pred l r)
  (letrec ((merge-aux
            (lambda (pred left right result)
              (cond ((and (null? left) (null? right))
                     (reverse result))
                    ((and (not (null? left)) (not (null? right)))
                     (if (pred (car left) (car right))
                         (merge-aux pred
                                    (cdr left)
                                    right
                                    (cons (car left) result))
                         (merge-aux pred
                                    left
                                    (cdr right)
                                    (cons (car right) result))))
                    ((not (null? left))
                     (merge-aux pred (cdr left) right (cons (car left) result)))
                    ((not (null? right))
                     (merge-aux pred left (cdr right) (cons (car right) result)))
                    (else #f)))))
    (merge-aux pred l r '())))

(define (merge-sort xs pred)
  (let loop ((xs xs)
             (result '()))
    (cond ((and (null? xs) (null? (cdr result))) (car result))
          ((null? xs) (loop result xs))
          ((null? (cdr xs))
           (loop (cdr xs) (cons (car xs) result)))
          (else
           (loop (cddr xs)
                 (cons (merge < (first xs) (second xs)) result))))))

Code to solve the problem

An easier way to do this is to “include” the code samples from somewhere else. Then you can maintain the code samples in separate files where you will edit them with the right support for syntax highlighting and indentation from your favorite code $EDITOR.

The particular inline syntax I’ve settled on for this is as follows:

{include code_dir/YourFile.java}

Where code_dir is a directory containing all of your code samples, and YourFile.java is some random Java source file in that directory. (It doesn’t have to be Java, it could be any language.)

The include syntax is not that important. What’s important is that we can easily maintain our code and text separately. We can edit Markdown in a Markdown-aware editor, and code in a code-aware editor.

Then we can build a “final” version of the Markdown file which includes the properly formatted code samples. One way to do it is with this shell redirection (see below for the source of the expand_markdown_includes script):

$ expand_markdown_includes < your-markdown-file.md.in > your-markdown-file.md

This assumes you use the convention that your not-quite-Markdown files (the ones with the {include *} syntax described here) use the extension .md.in.

Another nice thing about this method is that you can automate the “include and build” step using a workflow like the one described in Best. Markdown. Writing. Setup. Ever.

Finally, here is the source of the expand_markdown_includes script. The script itself is not that important. It could be improved in any number of ways. Furthermore, because it’s so trivial, you can rewrite it in your favorite language.

#!/usr/bin/env perl

use strict;
use warnings;
use File::Basename;
use File::Slurp qw< slurp >;

my $input_file = shift;
my $input_pathname_directory = dirname( $input_file );

my @input_lines = slurp( $input_file );

my $include_pat = "{include ([/._a-z]+)}";

for my $line ( @input_lines ) {
  print $line unless $line =~ m/$include_pat/;

  if ( $line =~ /$include_pat/ ) {
    my $include_pathname = $1;
    my $program_file = build_full_pathname($input_pathname_directory,
                                           $include_pathname);
    my @program_text = slurp( $program_file );
    for my $program_line ( @program_text ) {
      printf( "    %s", $program_line );
    }
  }
}

sub build_full_pathname {
  my ($dir, $file) = @_;
  return $dir . '/' . $file;
}

Footnotes:

1

While I was writing this I decided to do a bit of web searching and I discovered this interesting Stack Overflow thread that mentions a number of different tools that solve this problem. However I rather like mine (of course!) since it doesn’t require any particular Markdown implementation, just the small preprocessing script presented here.

(Image courtesy Claudia Mont under a Creative Commons license.)

How to Write Documentation for People that Don’t Read

These are my notes from Kevin Burke’s talk at the 2015 Write the Docs conference in Portland, Oregon. Any brilliant ideas in the below text should be attributed to Mr. Burke. Any errors, omissions, or misrepresentations are mine. You can also
watch a video of Mr. Burke’s talk.

Kevin Burke

Eye scans show that users read in an F-shaped pattern, from top left down the left side.

Users don’t look at big blocks of text.

Do this:

  • meaningful text and images
  • starts of paras
  • links
  • bullets

Use bulleted lists, not walls of text.

Bulleted lists perform 125% better (2.25x) than paragraphs for getting people to retain information.

Use the Markdown format for Github READMEs so you can have bold, etc. formatting.

People skip things that look like ads; this means they SKIP BIG RED CALLOUTS.

(NTS: we use this a ton, think about revisiting)

Text can’t be too wide (shows JIRA’s REST API docs as bad example)

Text should be 65-90 characters wide, like books.

(NTS: “information scent”)

Biggest paragraph from Github thing has 2 sentences.

Users are also bad at searching; they also don’t try other queries (“one and done”).

There is often benefit to having subtly different variants of questions around, as people tend to ask and search using different words.

People searched for client SDKs at Twilio as:

  • helper libraries
  • client SDKs
  • API SDKs
  • library bindings
  • language-specific wrappers

Example question: “how do I forward a number to my cell phone?”

Meanwhile, the docs said: “How to do everything with an incoming call”

A user won’t associate this; it’s better to have targeted pages.

No one reads anything above or below code snippets.

Code snippets can often have implicit configuration (env vars, library requires, etc.).

There can also be typos in code snippets.

A lot of people are not familiar with pip/gem/etc., so you have to help them figure out how to use peripheral tools.

Twilio has JS that fills in snippets with your actual credentials so when you copypasta a code sample it’s runnable.

People copy the dollar signs from bash snippets.

(NTS: WTF?)

every user failure is a potential job to be done

Say you get an SSL error authenticating to the Twilio API.

What are you going to do? Google it!

None of the top google results are your actual docs (SO, blogs, forums, etc.)

(NTS: if your stuff isn’t on google, it doesn’t exist.)

transgression: docs behind a wall

At one point 50% of twilio traffic was from Google.

If you have a login wall, you’re throwing away 50% of your traffic.

transgression: providing pdfs

PDFs are not searchable.

WikiHow stole traffic from Twilio!

If users get an error message from you, put that exact message in your docs.

Error messages should be copypastable into the goog.

Validation as documentation; maybe we can improve the error message.

Suggestion: put the user’s input back into the error message string so your user can see what they passed in to cause the error.

Strings are easy to find/change.

Takeaways

  • break up text
  • first 3-5 words of every para
  • more links
  • care about SEO
  • EVERY PAGE IS A LANDING PAGE
  • your docs should always win on google
  • make error messages explain how to fix the problem
  • better yet, solve the problem for the user