Wandering Thoughts archives


Lab notebooks are not changelogs

Here's something from my previous entry that I should clarify: lab notebooks are not changelogs.

Lab notebooks and changelogs are two different things. Lab notebooks are scribbled at the time for yourself, and should include everything. Changelogs are written after the fact for other people, and should include only the things that actually turned out to matter.

In other words, changelogs are the sysadmin equivalent of lab reports and scientific papers. You can no more use a lab notebook as a changelog than you could submit a lab notebook as scientific paper, and for much the same reason; fundamentally, a lab notebook has observations while a changelog has conclusions.

(Changelog is perhaps not the right word; I'm using it by analogy to the changelogs that programmers write. Sysadmins write changelogs to document what you did and why: you did X to cure problem Y, or to achieve result Z.)

Another difference is the medium. Changelogs ought to be electronic for all the obvious reasons, while I think that your primary lab notebook ought to be paper, because it is more flexible and easier to use under any circumstances. At the same time, having a shared electronic lab notebook of some sort is so useful that reusing a good changelog system for it is awfully tempting (and I suspect that a lot of people do just that; certainly we do to some extent).

One corollary of all of this is that I consider changelogs to be (part of) documentation, but I do not consider lab notebooks to be. Lab notebooks are a memory aid.

sysadmin/LabbooksVsChangelogs written at 23:57:40; Add Comment

Page tools: See As Normal.
Login: Password:
Atom Syndication: Recent Pages, Recent Comments.

This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.