Florian Gilcher, Asquera GmbH


About me

Community organizer




This talk is not about API docs, but fully fleshed out, article style technical documentation like tutorials.


We never merge changes breaking our tests.

What about changes that break our documentation?

Can we test that?

An interesting case

Software documentation is an interesting edge-case of natural language interleaved with formal language (often code).

What should documentation provide?



The beasts

Third parties

Third parties

If you use downstream libraries and document interactions with them, you have to track this for those libraries, too.


Sidestep the problem

Don’t include code in your documentation.


Reap the low-hanging fruit

Work on documentation formats

Example: Service Profiles

Example: Service Profiles

(╯°□°)╯︵ ┻━┻

Sidestepping a problem isn’t much fun.

Better have some tools


Feature: output_hello_world   We can output the string "hello world" using the puts  method.   Scenario: Use puts to output "hello world".    Given a file named "puts.rb" with:      """ruby        puts "hello world"      """...


This writes a Ruby file, evaluates it and tests your assumptions. It uses Gherkins description features.





Python ships a mixture of method docs and runnable code: doctest

def factorial(n):    """Return the factorial of n, an exact integer >= 0.     >>> [factorial(n) for n in range(6)]    [1, 1, 2, 6, 24, 120]

Very nice if the scope is limited the module at hand.

Documented execution

When your test fits a table… Selenium:

<tr>  <td>open</td>  <td>/</td>  <td></td></tr><tr>  <td>type</td>  <td>email</td>  <td>florian.gilcher@asquera.de</td></tr>

Documented execution

Use selenium steps both as visual documentation and for testing.


Implemented by walkhub.

Documented execution

You might see a pattern

All these approches start out in with testing formats and build towards written text from there. They automatically follow the structure of the code.

Literate programming

Literate programming interleaves text and code. It it’s purest style, code has to marked instead of comments.

Literate programming

Implemented in Haskell: count.lhs

Count Count wants to count words today.For that reason, he asks the user to provide some. > main = interact wordCount>    where wordCount input = show ( length input ) ++ "\n"

Literate programming

Tools that use comments for text:

Literate programming

Great for one-file examples with long text.

Disemphases code structure.

Literate programming: caveats

Code is not literature.

An easy to understand text works from top to bottom without references. This is not true for good code.

Boilerplate really kills your reading flow.

Example: Padrino - from ground up

This is the wrong way around!

Good high-level documentation is not written code-first.

Why not attempt to solve to problem by starting with documentation and then referring to tested code?

Hypothetical code

Lets continue by defining a hello world application. [[application/app.rb:5::10]]

Referring to code

Talking to the machine about code is a hard problem.

Referring to code parts

The Gist

Documentation is a very interesting problem from a hackers perspective. Let’s improve!


For most daily applications, the technological problems are solved, but badly documented. We have a learning problem at hand.

Thank you!


All pictures by @dariocravero and myself.

Slides with links at: http://skade.github.io/presentations/unicorns.html

Fork me on Github