<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
	xmlns:content="http://purl.org/rss/1.0/modules/content/"
	xmlns:wfw="http://wellformedweb.org/CommentAPI/"
	xmlns:dc="http://purl.org/dc/elements/1.1/"
	xmlns:atom="http://www.w3.org/2005/Atom"
	xmlns:sy="http://purl.org/rss/1.0/modules/syndication/"
	xmlns:slash="http://purl.org/rss/1.0/modules/slash/"
	>

<channel>
	<title>Made of Bugs &#187; writing</title>
	<atom:link href="http://blog.nelhage.com/tag/writing/feed/" rel="self" type="application/rss+xml" />
	<link>http://blog.nelhage.com</link>
	<description>It's software. It's made of bugs.</description>
	<lastBuildDate>Thu, 18 Aug 2011 21:57:23 +0000</lastBuildDate>
	<language>en</language>
	<sy:updatePeriod>hourly</sy:updatePeriod>
	<sy:updateFrequency>1</sy:updateFrequency>
	<generator>http://wordpress.org/?v=3.2.1</generator>
		<item>
		<title>Lab Notebooking for the Software Engineer</title>
		<link>http://blog.nelhage.com/2010/06/lab-notebooking-for-the-software-engineer/</link>
		<comments>http://blog.nelhage.com/2010/06/lab-notebooking-for-the-software-engineer/#comments</comments>
		<pubDate>Mon, 21 Jun 2010 02:53:07 +0000</pubDate>
		<dc:creator>nelhage</dc:creator>
				<category><![CDATA[Software Engineering]]></category>
		<category><![CDATA[lab notebooks]]></category>
		<category><![CDATA[software]]></category>
		<category><![CDATA[writing]]></category>

		<guid isPermaLink="false">http://blog.nelhage.com/?p=254</guid>
		<description><![CDATA[A few weeks ago, I wrote that software engineers should keep lab notebooks as they work, in addition to just documenting things after the fact. Today, I&#8217;m going to share the techniques that I&#8217;ve found useful to try to get in the habit of lab-notebooking my work, even though I still feel like I could [...]]]></description>
			<content:encoded><![CDATA[<p>A few weeks ago, I <a href="http://blog.nelhage.com/2010/05/software-and-lab-notebooks/">wrote</a> that software engineers should keep
lab notebooks as they work, in addition to just documenting things
after the fact. Today, I&#8217;m going to share the techniques that I&#8217;ve
found useful to try to get in the habit of lab-notebooking my work,
even though I still feel like I could be better at writing things
down.</p>

<p>Here&#8217;s my advice for keeping a lab notebook as a computer scientist:</p>

<dl>
<dt>Use a text file</dt>

<dd> <p>There&#8217;s no need to use anything fancier. And if you&#8217;re writing
code all day, you can just keep your log file open in your editor of
choice, so that you don&#8217;t need to leave your hacking environment to
make a note of something. I&#8217;m an emacs junkie and use
<a href="http://orgmode.org/">org-mode</a> to keep all my notes, but use whatever you&#8217;re
comfortable with.</p>


<p>You could use a physical notebook, but unless you expect to want
documentation of what you were working on for some legal reason, I
don&#8217;t see the point. And most programmers I know hate writing things
out by hand.</p>
</dd>

<dt>Treat your file as append-only</dt>

<dd>One of the downsides of just using a text file is that you need to
enforce some discipline on yourself. It&#8217;s tempting to go back and fix
up things that have changed, or to keep editing a desgin description
as it evolved. But creating a perfect finished piece of documentation
is a different task. The point here is to have a log of everything you
do, not a single finished document. You can work on one side-by-side
with the (dated or even timestampped) append-only log.</dd>

<dt>Keep automatic backups.</dt>

<dd>Do this any way you want. I keep my log files in git, and have a
cron job that commits and pushes to a server every five minutes. This
provides at least two benefits. First, it applies an automatic timestamp (to
within five minutes) on anything I type, and second, it serves to make
sure that a recent version is available on my server, in case I switch
machines and want to keep working on a project.
</dd>

<dt>Train yourself to make regular entries.</dt>

<dd>

<p>Keeping this nice text file, regularly backed up, is useless if you
don&#8217;t record relevant things into it. Getting yourself into the habit
of writing enough down is tricky. One strategy I&#8217;ve found helpful is
to write down a list of &#8220;triggers&#8221; for situations that you promise to
always record. With an explict list of these that you&#8217;ve decided to
always record, you can get good at making a note whenever you perform
one of these tasks, which gets you into the habit of writing things
down. Here&#8217;s a partial list of some of the sorts of things I make a
point of writing down:</p>

<ul>

<li>Whenever I take a measurement. That is, any time I run
<tt>time</tt>, or look at <tt>top</tt> to figure out how much memory a
program under development is using, or similar, I&#8217;ll write down the
number and the circumstances under which it was recorded. I&#8217;ve found
that I almost always would like to have a better record of such things
later.</li>

<li>Whenever I do a non-trivial search and find a result. This can be
anything from googling for a solution to some problem where it takes
me several tries to find the right keywords, or grepping a large
codebase searching for the function that performs some task, or
tracking down some API function in documentation. If I wanted it once,
I&#8217;ll often want it later, and if it was hard to find, I&#8217;ll feel stupid
if I didn&#8217;t write it down.</li>

<li>Whenever I make an explicit design decision. If I&#8217;m thinking about
how to design some function, system, process, or whatever, I&#8217;ll stop
and take a moment to write down the options I was considering, and why
I made the choice I did. This ensures I can go back and remember why I
built a system the way it is.
</li>


<li>Whenever I wish I had written something down last time. This
should be obvious, but if you find yourself thinking &#8220;I know I did
this before; Why didn&#8217;t I take notes?&#8221;, you should
<strong>always</strong> make a point of writing it down this time, no
matter what excuse you come up with for why you really won&#8217;t need that
information a third time.
</li>

</ul>

<p>These categories are deliberately broad, but at the same time
well-defined. It&#8217;s fairly easy to train yourself to notice whenever
any of these points triggers, and remember to stop and write something
down. And that&#8217;s the first step to getting in the habit of writing
down everything that you&#8217;ll later wish you had written down.</p>

</dd>

</dl>
]]></content:encoded>
			<wfw:commentRss>http://blog.nelhage.com/2010/06/lab-notebooking-for-the-software-engineer/feed/</wfw:commentRss>
		<slash:comments>14</slash:comments>
		</item>
	</channel>
</rss>

