
Runnable Documentation: Code for Humans - samlambert
http://githubengineering.com/runnable-documentation/
======
vinceguidry
I have to deal with an ugly legacy app for my job. Every once in awhile I'll
have to do something that doesn't make sense to build into the app, so I'll
come up with a procedure for doing it at a data level. Usually these are
processes that run weekly / monthly / quarterly.

The first time I come up with a manual procedure. The second time I try to
automate some of it. Then over the next few iterations I fix issues with the
automation, as that step inevitably produces edge cases. They'll need special
cases that I'll have to work into the tool.

Eventually this produces a command-line tool with appropriate help text and a
README that outlines what the tool does, why, and what edge cases are present.

I used to wait until it was almost a finished product before writing the
documentation, but as I get lazier and lazier, I just don't care to dive into
the code I wrote last month, I just want a procedure for getting it done and
going back to screwing around.

So the first time I have to do this, I take notes of all the manual steps I
took to perform it in a markdown document. How did I massage the CSV, which
fields did I add, so on and so forth. This has the side effect of making
writing automation code way way easier the next time around. Next time I do
it, I look at it and I'm like, "WTF Vince, why didn't you note that the date
field can change formats?"

I, myself, am that person without domain knowledge, every single time I go
back and do something I might have done even yesterday. I just don't care any
more to maintain my own silos.

It also allows me to only be as ambitious as I feel like being. If I'm in the
middle of refining a process and I lose interest, I can just wipe out my work,
and do it the old way.

------
encoderer
In our experience, this is becoming expected behavior. Credit to Stripe here,
theirs is the first implementation I remember. At Cronitor we had a bug in our
inline documentation that didn't replace the examples. They were still valid,
though not copy-paste runnable. The bug was introduced in a release before
breakfast and we had bug reports about it by lunchtime.

