Are there any proven methods for keeping a computer science lab notebook? What sort of stuff goes into a CS lab notebook, and what notation is used? Are there any reliable ELN methods, preferably integrating with Git?

I want to keep a lab notebook that helps me keep a running narrative of my research as well as my programming, in the same way you would keep a natural science lab notebook. It would be handy to be able to write down what I'm doing as I'm programming, then when a bug mysteriously appears in the software, I can see the last time the software was working, see where the bug started, then read the running narrative in between to help figure out what is causing it.

  • 1
    What's a “lab notebook”? I'm unfamiliar with this terminology. Is this something you write as a researcher? Or as a student? Is that lab as in doing experiments, or as in a class? Is this something you need to do for some legal purpose (say, related to patent claims), or for a teaching institution, or for yourself? – Gilles 'SO- stop being evil' Jul 21 '12 at 18:45
  • 2
    I'm probably going to need more explanation in my question. I used to be a chemistry major, and I really miss lab books for doing research and solving problems. – Nick Anderegg Jul 21 '12 at 18:52
  • I'm working on a research project, and I really feel lost when it comes to keeping track of everything. There isn't one single source that I can look to for a rundown on my project. But, paper seems to not mess well with CS. – Nick Anderegg Jul 21 '12 at 18:55
  • I appreciate the question, but I don't think it fits this site: it's more about self-organisation in the context of research than about computer science. That is, if there are no issues specific to a CS lab; I don't see any. We have asked the mods of Academia whether your question fits better there. If the answer is positive, I guess we'll migrate it over to them. Tools specific to programming are probably ontopic on programming-related SE sites. – Raphael Jul 21 '12 at 19:14
  • 1
    Related: "Good practices for organizing notes" – user102 Jul 21 '12 at 19:38

I don't do CS specifically, but I do research in computational/mathematical Epidemiology, which similarly lacks a clear format for a "lab notebook" and where the electronic tools designed for something like chemistry and biology doesn't necessarily suit.

Honestly, I've tried a number of systems. A private Wiki, a variety of other electronic systems, etc. And when it came down to it, I went back to a traditional paper notebook.

I've ended up with a bound paper notebook where I keep notes about experiments and simulations being run, thoughts on direction for the project, and the occasional printout of results taped inside. This has, for me, worked far better than electronic systems.

| improve this answer | |
  • I might have to try this out. I really hate taping things in to a notebook, so I'll probably just keep anything printed in a separate folder and refer to them as Attachment 1, etc. I like to keep track of my thought process, and I was considering using Wordpress with a live blogging plugin, but I think I'll have to resort to paper. I like drawing diagrams, and Wordpress doesn't really support that. – Nick Anderegg Jul 22 '12 at 17:17
  • 1
    @NickAnderegg TiddlyWiki may be interesting for both of you. It resides in a single HTML file and can easily be carried around on a thumbdrive (or hosted on a webserver, obviously). Thus, it may be closer to a classic notebook than a hosted Wiki. – Raphael Aug 5 '12 at 11:09

I devised this method when trying to organize story ideas (as a side project). It (for me, at least) is adaptable to my robotics projects and Neural Net research.

The basics for are as follows:

  1. Feeds
  2. Phase 1 - [Discovery][Hacking]
  3. Phase 2 - [New Frontiers][Learning]
  4. Phase 3 - [Flagship][Publication]

"Feeds" is a Word Document containing... tweets. For example:

20180214_1322. Hyperbolic TanH is outperforming Sigmoid for the 2-input XOR.

I try to keep each one short and to the point. There are hundreds of them. If I think of something on the go, I type it in Google Keep on my phone and move it to the Feeds later. These include comments, observations, thoughts, opinions, expectations, and agenda items. If something requires later attention, I mark the line bold (to do). If I am looking for ideas, I scroll down through the file and mark "interesting" entries bold.

Phase 1 is the discovery or hacking phase. Here, I keep files documenting each beginning step. Example CAD drawings, initial literature, code that was "hacked-together," and short writings are kept here. During this phase, I figure out if a project is worth exploring, and often get my hands dirty.

Phase 2 is the learning and refining phase. In the event of a robot, all mistakes are documented. New code is created. Conference papers are prepared. Experiments are outlined. Characters are further developed.

Phase 3 is the publication or deployment phase. My robot is refined and ready for competition or "showing off." The book is now in the drafting phase to be presented to a publisher. A full research article, concluding a specific sub-area is research, is prepared for submission to IEEE.

The key, for me, is to name everything by the date it was originally created (meaning expansion from Feed to [whatever file is necessary]). If significant changes are made, create a new file. Sorting files by date would be OK for most, but I jump between clouds and operating systems too often, and this metadata is often lost. Significant versions of code are zipped away when seriously updated. Experiments (source code, raw output files, and Excel files) are zipped and dated accordingly.

Again, this is how I manage my projects and research. I imagine that a post-grad researcher would need to split these phases by each publication. The part I would recommend above all else to maintain is the Feeds. A chronological-order "change log" of all ideas, thoughts and changes has become indispensable to keeping things organized.

| improve this answer | |

I use Jupyter Notebooks as my (almost) all-in-one research environment. Jupyter is a locally-hosted webapp designed primarily to write code in a convenient interface in a web browser. The native language is Python, but there are kernels for many languages. Jupyter also supports writing text with Markdown and MathJax inline with your code. The notebooks can be exported as HTML, PDFs, slides, Markdown, .rst, or .tex files (especially useful when drafting papers for journals/conferences that provide a .cls file!). And because a notebook is stored as a plaintext JSON file, it's VCS friendly.

The next iteration, JupyterLab, is currently in the late-stages of development and is in beta.

| improve this answer | |
  • Are you affiliated with JupyterLab? – scaaahu Feb 15 '18 at 10:28
  • I'm not affiliated. – Chris Feb 15 '18 at 10:34
  • In contrast, back in my postdoc we referred to the Jupyter Notebook we were using as "The Wall of Madness", and I found it wholey unsuited for lab notebook use. – Fomite Feb 15 '18 at 23:04

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.