3 ms·

Runnable Documentation: Code for Humans

16 points by samlambert 11y ago

vinceguidry 11y ago
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 11y ago
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.

16 points by samlambert 11y ago

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 11y ago

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.