Why You Should Document Everything

This past year, I found myself really excited about consolidating all of my data for a manuscript I’ve been preparing. I thought: ‘Hey, I analyzed most of my data already, this shouldn’t be too hard’.  My dear reader, I was so wrong. My original sin was that I didn’t document exactly HOW I analyzed the data the first time around. Why is that a problem? Well, when I wanted to add new cells into the analysis, I had to re-analyze all of my data again because I didn’t remember the parameters I used in the first place. In short: I did not document everything.

What was I thinking? The correct answer is: I wasn’t. Past me had assumed that she would remember what she did to analyze the datasets. Current me was forlornly flipping through her notes. Clicking random computer documents for some clue of how the analysis was originally performed. In the back of my mind, I knew there weren’t any clues.  Don’t do this to yourself. If you become Indiana Jones to trace your workflow history, you’re going to start questioning your place in this universe. Instead, make sure to make a note of exactly what you do and how you do it.

As an example, for the manuscript I’m working on, I’ve created folders for each individual figure. The folders contain:  (1) the figure in the Illustrator file, (2) past versions of the figure, (3) the data in each figure, and a (4) text file with directions of how I analyzed the data. This system helps to keep everything in one place. You will know where to look whenever you have questions about what your previous self did.

Make a Habit – Document Everything

The habit, document everything, should also extend towards designing your paper figures. I don’t know about everyone else, but I’m still living in the Ice Age when it comes to designing plots. Usually, I make my bar and line graphs on Excel or Prism, and then I copy + paste those plots into Adobe Illustrator. Thus, I don’t have a good way of standardizing the width and lengths of the bars or the size of the sub-panels. I have to re-size everything on Illustrator.

I assure you that you’ll go through countless iterations of figure edits. I’ve learned the hard way that you should write down your exact workflow when creating these figures. If you have to scale down your exported Prism figure by 33% in sub-panel B, write that info down! Or else you’re going to have a miserable time eye-balling everything, and no one has time for that. Every time you think it’s an inconvenience to write down this information, be assured that your future self will thank you.

For all Workflows

Everybody who uses code should also adhere to the same principles. It’s always good practice to comment your code. This isn’t just for your own benefit, but also for the benefit of anyone else who may want to use your code in the future. Using programming languages like Python, R, and Matlab to streamline your analyses is a great way to make sure all of the analyses are completed in the same way. For more extensive analyses, writing new functions to perform your analyses can drastically speed up your workflow. However, we can run into the same problems of having to repeat analyses if we forget our initial parameters. Therefore, make sure that every output file contains information about the parameters you use in the analyses.

In conclusion, learn how to love yourself and your sanity by taking notes on the specifics of your analysis and figure-making.

What did we learn today? Document everything. 

__________________________________________________________________________________________________________________________________________

You can find our next tip in our Reach Out post!

If you just want to reach out to us, or want us to refer you to a place you might get your questions answered, send us a DM/tweet!