Keeping a Lab Notebook

Just like with wetlab work, it's important to document everything you do during a computational workflow.

Where to take notes

For this project, we recommend using HackMD. HackMD works a little like google docs, but enables better formatting for adding code. You can start with just regular text, but as you start adding screnshots, code blocks, and header sections, you can use Markdown syntax to improve formatting of your rendered notes. HackMD shows you a few examples of Markdown when you first open a new document, but you can also check out this markdown tutorial if you want to learn more.

How to take notes

It's ok to provide the minimum amount of information necessary to execute a set of commands (i.e., you don't necessary have to record every failure, every ls, etc), but it is important to document each step. + Copying and pasting the commands that worked is a great way to record them (the history command can be helpful to see what you've run in the past).

Documentation is for you! (And also for others)

Your lab notebook and documentation is most useful for future you. Keep in mind that things that seem super obvious right now will likely be forgetten within a few weeks/months. Try to be detailed enough so that if you tried to pick up this project again in 3 months (or 3 years), you would be able to understand exactly what to do and how to do it. With a good lab notebook, you can save yourself from troubleshooting the same errors over and over again, as well as greatly simplify the process of writing up your Materials and Methods section for any reports or papers. Finally, good lab notebooks help keep everyone working on your project (both now and in the future) on the same page.

Other systems for taking notes:

After this project, if you like HackMD, great! Stick with it. If not:

• Using google docs or Microsoft Word for documenting computer commands can be hard because of autocorrection. We generally recommend against using these programs.
• Using a plain text editor (Notepad, Notepad++, Atom, BBEdit, TextEdit, nano, vim) avoids autocorrect problems but still has a nice user interface.
• Jupyter Lab is very useful for interactive research explorations and notetaking. We'll try this out in a later section.

Eventually, we'll work through using git and GitHub to record and version control our workflows, but for now it's enough to write down everything you do.