Taking a Break: Some Stories of Documentation

I’ve been thinking a lot about documentation this month as I prepare to take 12 weeks of leave away from my job. The upside is that I’ve had 9 months to plan for this, but I will also say that following good data management and reproducibility practices has greatly helped with the efforts to shift my duties temporarily to others.

In today’s post, I want to provide some snapshots on how I’m documenting tasks so that others can perform them in my absence. I’m hoping that these vignettes will provide inspiration for others aiming to provide enough documentation with their work, whether they are taking leave or not.

Story #1

My smoothest project to shift involved some R code I wrote over the summer to run automated reports for my library’s public services statistics. I knew going into the project that I would not be able to run the reports myself during the key period at the end of the semester, so I made sure to document everything at a level for a novice to pick up. In practice, this meant including a README.txt to walk someone through everything from installing the software to adjusting key variables to running the code. I also tried to make clear within the code, via commenting, which parts needed to be updated to customize the reports. Building code with the intention of it being used by others is really the best practice, and I can see the benefits of taking this approach that will help beyond my 12 weeks away.

Story #2

Another task I’m temporarily shifting is acting as Secretary for my professional association. Again, I’ve helped myself a lot here by having a good README.txt file laying out the structure and permissions for all of the files I manage as Secretary. So it was simply a matter of adding notes on my duties so that they could be adequately covered.

Story #3

A more involved project to shift is a research project I’m on for which I have an assistant. Key documentation here included a timeline for assistant onboarding tasks and a lot of communication with my collaborators. The timeline turned out to be a good idea, generally, as expectations are clear for everyone; this is likely a method I’ll use in the future. Otherwise, I’m trying to go for a more-communication-is-better approach, which requires extra work but will benefit everyone when I’m away.

These three vignettes show [what I hope are] successful efforts to document tasks for others. I think what makes them good is that I’ve built a lot of the documentation into the projects to begin with, making it easier for me to pass stuff on now. I admit that not every project I run is documented to the levels described here but my future self is usually more grateful than not for taking 10 minutes early on to write a README or send a status email.

I hope these stories provide you with some ideas for your own projects that may need to be passed along or picked up again by your future self. Even a little documentation created early in a project is helpful and usually doesn’t take a huge amount of time to create. The benefits to your collaborators and your future self usually make it all worthwhile.