Process documentation or ‘rest of the fucking owl’

[creating the] rest of the fucking owl is a meme that was born of a photograph showing the process for carving an owl statue wherein the process was impossibly under explained. Of three steps there was step one: a block of wood with a basic owl stencilled; step 2: the owl roughly cut out; step three: a beautifully carved owl statue. I won’t labour the point here, but similar examples are common in drawing tutorials where you go from basic shapes to a full sketch in one step.

And, curiously enough, this meme is extremely applicable to researchers because, as anyone who has had to take over someone else’s project (or return to their own after a break) knows, things that made perfect at the time often make no sense whatsoever later on. I learned early on that I barely remember why I did something a particular way the next day, let alone 6 months later, and have developed metadata systems, file naming conventions and standard code names to help future Erinne (or future anyone) understand what on Earth was going on when I decided to do option a.2.1.5 (success!) instead of option a.2.1.4 (sneaky looks right but is actually wrong). I suspect an awful lot of the downtime associated with a project changing hands or with learning a new process in a new institution comes down to a lack of meaningful process documentation.

Some ideas on things need to be included in process documentation:

  1. What is the process? Why did you use it? When would you not use it? Is there any relevant background information that needs to be understood?
  2. What is needed? If ‘it depends’, then how do you find out?
  3. How is it done? Why?
  4. How do you know you did it right?
  5. What downstream processes can be used?

In the case of data processing/analyses, it’s useful to know what you did, why you did it, and what it should look like if it’s going to be something strange. Future you will be grateful that you spent an extra few seconds here and there explaining what you did and why, trust me on that.