
Keep a programming journal - feyyaz
http://gist.github.com/3444793
======
babarock
As long as we're on this subject, I'd like to strongly encourage programmers
to adopt a "pen-and-paper" approach to problem solving. Just like mentionned
in the article, there are great benefits coming from actually writing down the
problem.

For the past year or so, every time I worked on a non-trivial problem, I did
it on a sheet of paper. It definitely took discipline at first but now I
couldn't do it any other way.

My motivation for adopting this approach came from reading a blog post by
Guido Van Rossum (<http://neopythonic.blogspot.fr/2011/07/before-
python.html>).

    
    
      Then I went to university in Amsterdam to study mathematics and they had a computer that was free for students to use!
    
     (Not unlimited though. We were allowed to use something like one second of CPU time per day. :-)
    

"One second of CPU time per day" got me thinking. Sure there are benefits to
having modernly cheap computers, but how did they do it before?

~~~
kellishaver
After switching to a Model M keyboard a few years ago (one that I found in a
shed covered in 10yrs of dirt and grease that still worked like new once it
was cleaned up), I switched to writing conference call notes on a Mead
notebook instead of typing them, because the keyboard was so loud.

After a few weeks of this, my handwriting got back to a decent quality and
efficiency and now I find that I take notes on paper for all sorts of things.
It's great for working through problems.

I tried a whiteboard for a while and it just didn't do it for me. I think
there's something about the tactile experience of holding a notebook in my
hand and scrawling on it with a pen; the movement, the sound, the texture of
pen on paper, not to mention being able to keep and flip through previous work
and go back and make notes in the margins that makes it far better than trying
to work out problems on a computer or a whiteboard.

~~~
eckyptang
+1 but I use a mechanical pencil as you can rub stuff out, it's immune to
coffee spills and you can file your nails down on the knurling when you are
thinking (Rotring 600 recommended).

I am sometimes ridiculed for such low technology though which I find rather
strange. I think there are some serious cultural identity problems at the
moment.

~~~
kellishaver
I usually end up writing with a pen because I find the greater level of
contrast easier to read; I have pretty bad eyesight. Lately I've been using
fine-point Sharpie pens and they're great for readability.

I do a lot of pencil drawings, though (<http://orng.us/ob8yao>) and I do find
something magical about the feel of pencil on paper, and even the smell of the
graphite. I can lose myself for hours. But if I'm writing, I like a darker
line, which means softer lead, which means more smudging.... bleh.

~~~
Mystitat
I've found that fine-point sharpies bleed through every kind of paper. What
kind of paper do you use?

~~~
kellishaver
Just a Mead 5-subject spiral notebook. It's not super thin paper, but it's not
really heavy, either. I've never had an issue of bleed through, but I don't
write on the back side of the page, either.

A Pigma Micron might work well for you: <http://www.sakuraofamerica.com/Pen-
Archival>

------
asynchronous13
My background is in Electrical Engineering, and we were always taught to keep
a work journal with specific features so it would be a legal document. I just
figured they were trying to sell us the more expensive notebooks. That is,
until some colleagues were called to court to testify in a patent challenge
about the contents of their journals (regarding work from 10 years prior). I
take my journal a lot more seriously now.

If the notebook is bound (can't add or remove pages), with pre-numbered pages
(proves no pages added or removed), and entries are dated, it's pretty much
automatically admissible in court. Loose or missing pages, hand written page
numbers, missing dates -- won't necessarily make it inadmissible, but it
leaves room for the work to be challenged by the opposing team.

~~~
autotravis
"If the notebook is bound (can't add or remove pages), with pre-numbered pages
(proves no pages added or removed)..."

Does anyone know of a good place to get an inexpensive (and leatherless) one
of these? I would say any notebook would work, but I haven't ran on to many
with numbered pages.

~~~
brainid
The National Brand Computation Notebook is popular. $12 from Amazon.

I have used them for years.

~~~
richardjordan
Thanks for the tip - nice notebook - I wish I could get a nice hard cover book
WITH numbered pages.

~~~
lallysingh
Available off of amazon: <http://www.leuchtturm1917.com/>

I switched from moleskines, and have been quite happy.

~~~
richardjordan
nice tip

------
getriver
OP here. This is a pleasant surprise, I woke up this morning and saw the title
and for a split second thought someone wrote the exact same post as me!

Reading the comments on here and reddit, it seems to me there are two
different motivations: getting thoughts on paper vs. having a trail for future
reference. Pen and paper is great for the former, which is my primary
motivation.

I highly recommend you try the paper approach at least for a week to see if it
helps you. Its is a hassle switching gears from keyboard to pencil, but it
helps a lot. I did try various programs, but it never felt personal enough for
me. Maybe its just me.

------
agentultra
Do this for every hobby you have as well, whether carpentry, learning
Mandarin, or reading.

Keeping a record of your thoughts is so useful in establishing how you arrived
at your current opinions. It helps you to make the mirror on yourself much
clearer. I find it immensely useful to look at how I've approached problems
and discover new insights from the patterns I can glean in my journals.

Plus it leaves behind a record of yourself in meat-space. Depending on the
nature of the up-coming apocalypse this might come in handy.

------
tylerneylon
Paper and pen(cil) notes are the ultimate in low-overhead for a temporary
close-to-mind data store.

I would disagree about the author's advice to use page numbers and table of
contents, though; these add overhead, and for me the main advantage is ease-
of-use, including close to zero extra work when writing something down. (Dates
are useful, I admit.)

I keep a paper coding notebook of anything I might possibly refer back to ever
-- things like basic how-to's on using new technologies, or diagrams of how
I'm structuring my code.

I also use a simple open source work journal (nicknamed wj) that helps me make
sure I'm on track in the scope of days and weeks. My plan is to end up with
one or two sheets of paper that summarize what I did throughout a year - this
is a great personal motivator to make sure I'm doing work that a future-me
will be happy with. <http://tylerneylon.com/a/wj/>

~~~
billswift
Page numbers and table of contents are very important for finding the info
again. Also, they don't have to, and shouldn't, interfere with note-making. I
number the pages before I start using a new notebook, and add things to the
ToC at the end of the day when I do a quick review, when I also make out
tomorrow's to-do list.

~~~
tylerneylon
Numbering pages ahead of time sounds like a good way to avoid time-of-writing
overhead.

I write down a LOT of my thoughts as I work - most of it I never refer back to
again after that day. I like to use book darts (maybe two or three per
notebook) to mark things I do refer back to more often.
<http://www.bookdarts.com/>

------
pingswept
I've been keeping a project journal in a series of notebooks for a few years.
As I've filled more and more notebooks, I miss the searchability of
computerized journals. For a while, kept a text file open all the time and
tried using it as a journal, but that's lousy for any kind of sketching.

My most recent attempt has been a pile of Markdown files in a Github
repository. I edit them directly in Github's editor and they are automatically
rendered by Github, so I get nice syntax highlighting and working links. It
has the added advantage that I can send people links to whatever I'm
struggling with, like "Here's the error message I'm getting: <link>."

Here's my log: <https://github.com/pingswept/dev-log> (Obviously, this only
works because most of what I do these days is open source, but it could work
just as well on an intranet.)

I've been creating a new file for each day's log, but I think that might not
be quite the right approach. It makes searching a little more difficult
(though still much easier than notebooks), but makes editing easier because I
don't have to scroll to the bottom of a huge file to start typing.

If anyone has suggestions of better ways to do this, I'm definitely
interested.

(Hmmm. Maybe there's a keyboard shortcut for skip-to-bottom-of-file in the
Github editor. _Edit: hey, there is! Command-down-arrow._ )

~~~
follower
I've mentioned Labradoc (<http://labradoc.com/>) elsewhere on this thread but
it seems like it might be worth you considering it too.

More so, if it doesn't suit you I'd be interested to know why--given you seem
to have implemented a more manual approach to what Labradoc aims to do.

The major difference from what you've described is that Labradoc has a
project-based rather than day-based focus. (Although there's no reason why a
"day view" couldn't be an option...)

(Labradoc also uses Markdown.)

~~~
pingswept
I actually noticed your Labradoc comment earlier and took a look. It's more or
less what I'm looking for, without the weirdness of being embedded in Github.
There are 2 reasons I'm not switching to it right now:

1\. My system already works fine.

2\. The default styling of Labradoc doesn't suit me. The blue/purple links and
left-aligned text have a 2005ish look to me. Those would presumably be pretty
easy to fix with a CSS overlay of some sort, but that would require a little
tweaking.

But still, Labradoc looks like pretty much the same solution that I came up
with, so I like it!

One suggestion: make the example have a link or screenshots to something that
shows the Markdown side of things. Is there an editor? What does it look like?
Even a screenshot tour would help lure people in.

------
roedog
I've kept an engineering notebook for years. It was something I was told to do
in college. It seem that the act of writing down the problem slows me down
enough to focus my thoughts more on the task.

I've tried keeping notes on the computer and they are useful. But, I've never
gotten the same level of focus from writing in an online journal. I wonder if
the focus comes with practice. I type much faster than I write longhand, so
perhaps I lose the trigger of slowing myself down.

------
follower
If you're interested in a digital approach to this, take a look at Labradoc
(<http://www.labradoc.com/>) a site I created to make it easier to keep
project logs.

I primarily created it for myself (<http://www.labradoc.com/i/follower>)
because getting into the habit of creating project logs had a huge positive
impact for me.

Here's an example of a small project I worked on earlier this year:
[http://www.labradoc.com/i/follower/p/project-sms-text-
scroll...](http://www.labradoc.com/i/follower/p/project-sms-text-scroller)

I consider it a form of a "commit log for your day"...

------
imperialWicket
This is spot on.

I love the soft-leather grid notebooks from miquelrius (no affiliation
whatsoever, but I always get comments about them):
[http://www.shopmiquelrius.com/servlet/the-553/Flexible-
Noteb...](http://www.shopmiquelrius.com/servlet/the-553/Flexible-Notebooks--
dsh--Graph/Detail)

I always keep one of those handy, as well as a whiteboard. Together they serve
as my rubber duck and todo list; no matter what apps, services, etc. I've
tried, I always come back to pen/paper and marker/whiteboard - it just works.

------
JoeAltmaier
A customer demanded I keep notebooks, dated an initialed on each page; I've
never stopped. They wanted it because they are a patent mill (they have
hundreds, file dozens annually). I do it because I can review what's done,
whats left; keep todo lists up to date easily; keep lists on the right page,
scribble notes on the left; find out when something started, when it finished.

Hard to draw diagrams in most todo-list apps; where do you jot phone #s,
debugging constants, interview notes?

------
wonderzombie
So does anybody have tips about how to take good/useful notes? I feel like my
stuff, while organized by topic, ends up being disorganized and quite ad-hoc.
I feel like I'm missing out on something since I don't have any real system or
technique beyond "write down stuff like you're explaining it to your future
self" or some such. Maybe it's enough just to be writing all that down.

~~~
getriver
Its a trial and error process. Write down as much you can without slowing down
too much and then try to read back in couple weeks and see if it makes sense.
The longer the gap in betweenm the better since your memory disintegrates and
you're left with just the information on the paper.

~~~
wonderzombie
_Its a trial and error process._

I was afraid of that. :) But yes, I see your point. I suppose it's hard to do
better than: think of what your future self would need to know, providing both
context (to jog your memory when possible), rationale (because that is NOT
always obvious), and technical detail (both because that stuff changes and
because it's better not to re-derive your previous understanding from scratch
whenever possible).

------
JamesLeonis
I started doing this when my last job offered free spiral bound notebooks. For
a couple of years I've kept an intermittent traditional journal, but I've
found many were too cumbersome for my hands or my writing. The spiral bounds
have the advantage of cleanly flattening out when open and going from one page
to the next. The page size suited me for both long form writing as well as
enough space to draw out visual diagrams. They also help when I start up the
next day, as I know what I was thinking from the day before.

I kept written notebooks for several years now. These contain anything
including scratch paper, programming logs, long form writing, and ideas. I use
standard spiral bound notebooks that always go on sale this time of year for a
buck. They are reasonably well made and stand up to the abuses that I throw at
them. Right now I am carrying three of these with me along with my laptop. My
current notebook has four website ideas, one story idea, one game idea, and
nearly two dozen short essays.

At the top of the page, I generally give a title to what I'm doing. I have
some common labels, like what the project is or the title of a short essay.
Right now I don't have a way to organize it, so I'm usually flipping to find
what I'm looking for. Sometimes I become distracted by reading about something
else I wrote months before, and it would inspire a new essay or idea.

I'm currently trying out some ways to digitize my old journals so I can put my
old notebooks in long term storage and not disturb them. If anybody has some
suggestions, I'm open :)

------
lelandbatey
I agree, though I would extend the call to more than just a programming
journal.

All my life I've been told that keeping a journal would be a worthwhile and
valuable experience. However, I could never stick with it for more than a few
days or a week at max.

Cut to this summer, where I got my first "real" job, and made friends with a
very cool guy[1]. At some point, he mentioned how he adapted the idea of
journaling into his life. He had encountered the same issue I had, where he
could never keep a journal for any amount of time. Instead, he bought a
moleskine large notebook and began using it for notes of all kinds.

The genius is that while it is an organizational tool, it also acts as a "no-
effort journal." He showed me all the things he had been working on and
thinking about just by looking back at the previous pages of his notebook.

With his advice in mind, I have also started keeping a notebook just to write
things down in. It's tremendously helpful for my own organization, and it
gives me a clear view of all the things I've had on my mind.

In short, I recommend a notebook for everything in your life, not just
programming (although a separate programming notebook may be worthwhile to
you).

[1]<http://adamryman.com>

------
zrail
I have a web app that I've been using for awhile for this kind of thing. Each
note is a markdown document that's versioned in a database. I can create new
notes via email (using the excellent Mailgun). There's also a pretty full-
featured API which lets me do interesting things with notes.

My original goal for it was as a way to get ideas out of my head and onto
"paper". It used to be that I would have an idea and then it would circle
around my head for _weeks_ while my subconscious tried to work out all the
implications.

The thing I use almost every day, though, is the append API call, which just
appends a timestamp and some arbitrary markdown to an existing note. I wrote a
little script that appends to a particular note, and I run it automatically
after consequential actions at work. I also use it to write journal entries
about what I'm working on, both for work and side projects.

I've been meaning to get it fit for public consumption and set up somewhere
but I haven't gotten around to it. If anyone wants to give it a test run, let
me know. If there's a market I might just try to monitize it :)

~~~
follower
> My original goal for it was as a way to get ideas out of my head and onto
> "paper".

Yeah, I've found a project log as a good way to get an idea out of my head too
--or out of the tabs in my browser :) until I'm ready to get back to it.

Sounds like your app has some similarities to my Labradoc site
(<http://labradoc.com/)--I> haven't yet succeeded in being able to monitize
it. :)

------
MojoJolo
I also have a pen and notebook. I used it to write algorithms or some ERD that
I'm currently doing. Nothing beats thinking with pen and paper.

------
sgt
I do the same thing, but the extent of my "legend" is simply the following:

"->" (random points)

"o" (random points)

"[ ]" (thing I need to do)

"[/]" (thing I need to do, in progress)

"[?]" (I don't know what to do, might revisit)

"[-]" (Not going to do this one, maybe it became redundant)

This helps me a lot to line up my thoughts and know where I am. However, I
really like the legend as described by OP, so I might change mine towards that
approach.

------
kabdib
I use various sizes of acid-free Strathmore Sketch books. Nice surface for
drawing or sketching, and they're relatively cheap.

Different size notebooks for different size ideas. A friend of mine (who I
stole this habit from) said he had a coffee-table-sized sketchbook at home
that he'd never used, because he'd never had an idea that big. :-)

------
Johngibb
I've been doing this as well. Does anyone have advice on pens?

This is what I'm currently using and I really like them:
<http://amzn.com/B0027AEKJ8> they come in a 4 pack of different thicknesses,
and are only $12 at Staples. I'm sure there's better however!

~~~
Glide
I got a fountain pen when I wanted to improve my own handwriting just to see
what is so different about them. I bought a Lamy Al-Star pen, a converter, and
a bottle of ink. I would never use an ordinary ballpoint pen if I can help it.
Writing with a fountain pen seems so much easier than writing with other pens.

~~~
expralitemonk
I have a Lamy Safari pen and love it. Light, durable, ink level indicator. My
penmanship has improved quite a bit since using it.

------
nlh
So despite the great ideas and tales of pens & paper (and moleskin) here, I'd
love to hear some thoughts on good digital solutions to the programming
journal.

I use and am totally in love with Day One (iOS & OSX) for my personal journal:

<http://dayoneapp.com>

It could very easily be adapted into a programming journal (it supports images
w/ each entry & monospace fonts, which are both great). Unfortunately, they
don't yet support multiple journals, so that's out as an option for me on the
programming side.

Any thoughts / suggestions on good apps that will fit the bill? I know about
Evernote but would love something a bit more "journal-specific" and perhaps
better suited to this task...

~~~
gcr
Bend org-mode to your will!

<http://orgmode.org/>

I have a org-mode "capture" keybinding set up so I can just hit a key while
programming and a small popup buffer asks me for some notes on what I'm
thinking about. It can then add it to tomorrow's TODO list or perhaps a
journal file/folder of my choosing.

Best part: because it works with Emacs, it doesn't break my flow. I can just
capture thoughts while coding and immediately get straight back to coding.

------
mikle
I think that dead paper is not the right medium for this. I love OneNote and
how flexible it is. I can quickly open a note (faster then notepad on my
machine) to jot down a todo or some snippet I need or I can open my project
notebook and see all my "design meetings" (with myself) and it is searchable
AND there is a way to encrypt sections. I've put my OneNote notebooks on
dropbox and that's basically a perfect system for me.

The two things this is weak in are sharing and not having a leather bound
tactile notebook and pen to play with which I must admit looks pretty cool.

------
kstenerud
All my notes (of which there aren't many) are kept in text files in a well
known directory, along with all my code. I can grep for things I've solved or
thought about in the past and get the information instantly. And since it's
electronic, I can back it up, copy it, and access it from anywhere.

The only times I've found myself needing paper is when dealing with graphics
programming, in which case it's simply for figuring out the best way to tell
the computer how to do something. Once it's in code, I don't need the paper
anymore; I can just grep for it.

------
stcredzero
At first, I thought that this was for developing productivity habits.

[http://lifehacker.com/281626/jerry-seinfelds-productivity-
se...](http://lifehacker.com/281626/jerry-seinfelds-productivity-secret)

I used to like putting stickers on a calendar as a kid for this sort of thing,
and I wanted to do that on the phone but found that most electronic calendars
aren't so good for that. So I developed an app to let me do that.
<http://www.ooghamist.com/shinycal/>

------
mmcnickle
Yep, I have a bound notebook for each project I work on. It's great for seeing
how and why you arrived at a certain point. A habit from keeping lab books at
university.

I use a thin (0.5mm) mechanical pencil.

------
wzhack
I actually use paper a lot. It is especially helpful when I am away from
computer and I need to design a code flow, algorithm or just write down
feature or todo list. Paper and pen rocks!

------
roqetman
I've learned to keep a log of all the work I do (so I can search for
information on request or if I want to recall something months or even years
later), but I just use a specially formatted vim file (that has references to
other scripts etc. if needed). More recently I've started a personal version
of this to keep me on track with my own app projects. I love the look'n'feel
of a physical journal, but it's just not practical in the long run for the
work I do.

~~~
pnathan
I keep an org-mode file in emacs as a log of thoughts and actions. It's pretty
useful, especially as as a retrospective.

------
aidenn0
How does one develop the habit of keeping a journal? I've tried several times,
but have never made it more than 3 weeks before I started to forget to do it.

~~~
getriver
* Write date in journal first thing in the morning when you wake up and keep the journal open next to you while working. This reduces the friction of starting.

* Look back at it at the end of the day and see what you've done that day. This is your reward for using it. Alternatively you could have your own reward.

* If you forget to do it today, restart tomorrow without any fuss. Don't worry too much about the lost day, like I used to.

In the beginning I was pretty excited about it and it was real easy, but after
couple months it got a little old. Eventually I got around to the point where
if I don't write in the journal while working I feel uneasy.

------
ENOTTY
This is a great idea that I've been practicing with not as much discipline as
I would like. I've been slowly converging on an optimal (for me) paper size. I
use the Pilot G-2 pen which writes well and feels good but is still cheap.

But I haven't been able to find a paper that is thick enough to allow for
double sided writing. The composition pads tend to have really thin sheets
that the ink shows through. Does anybody have suggestions?

------
southphillyman
What kind of developer doesn't keep notes? 1 half of 1 wall in my bedroom is
WHITE BOARD. The first thing that I'm greeted with when I wake up in the
morning are problem sets and notes on my bedroom white board! I have note
books from 2004 full of notes and pseudo code. I have EverNote and I have
Notepad++. Note taking and diagramming/planning is SO essential in my opinion.

------
Reltair
Does anyone happen to know if there are any leather bound notebooks with pre-
numbered blank pages?

Moleskine notebooks look promising, except they aren't really leather and
don't have pre-numbered pages. I guess I can number the pages myself, but it
would be nice to already have it done.

~~~
getriver
The only numbered notebooks I've seen are daily planners. Moleskines are
leather, though not sure about the quality.

Edit: Saw these in comments:
<http://www.leuchtturm1917.com/de/content/startseite>

~~~
Reltair
Those fit with exactly what I was looking for, thanks!

------
expralitemonk
To improve your handwriting legibility, write in italics. (Cursive seems to be
write-only.)

[https://www.nytimes.com/interactive/2009/09/04/opinion/20090...](https://www.nytimes.com/interactive/2009/09/04/opinion/20090908_opart.html)

------
expralitemonk
I use Clairfontaine "Life Unplugged" notebooks for brainstorming, todo lists,
and problem solving. Yeah, they have a hipster vibe, but the notebooks I buy
at the office supply store fall apart after two weeks in my pocket. These last
awhile.

------
lenkite
I use Google tasks and an android app. There isn't currently a great desktop
app for Google tasks and I don't like the gmail web interface for tasks so I
am building one in C# using AppBars. I guess I publish to HN when done :p

------
samspot
I think this is probably fantastic advice, but I can't seem to let go of the
searchability of electronic notes. It is also nice that I mostly do not need
to worry about things like losing the notebook or filing old ones.

------
Feoh
I wish the article had a bit more meat to it. Not that this is a sin but he's
just parroting things said in about 1000 other places by 1000 other people.
Pen and paper good. Check. Daily journal. Check.

~~~
keithpeter
The OP is keeping a journal, so he has developed a real practice that works
for him. I agree that a few sentences _describing_ what he puts in there would
have made this article stronger.

The second image of the journal page seems to show a list of possible
approaches to a problem. The fourth image looks as if it has performance data
and evaluation of a working system, so that is a couple of ideas. I think it
is quite a brave thing to post the actual images. Perhaps fortunate the OP
does not record _team dynamics_ in his journal.

I work as a teacher, and I use a cheap page a day diary to record a few key
points from each lesson. The 'readymade' aspect of the page a day diary seems
to reduce the 'threshold' for making notes.

~~~
getriver
It usually goes:

* Write a todo. Ex: Log errors from Fb. * Ask a question if I'm stuck. Ex: Will Log4R block the reactor? * Play with various approaches. Ex: Write in thread, plug into Goliath's logger. * Note any bugs. Ex: Logger blah blah * Rinse and repeat.

I know its a silly example, but you get the idea. Hope that helps.

------
xbryanx
I love the idea of keeping a programming notebook, but I'm still waiting for
the searchable pen and paper notebook. Until then, I'll stick with Notational
Velocity.

~~~
_pius
Here ya go: [http://blog.evernote.com/2012/08/24/the-new-evernote-
smart-n...](http://blog.evernote.com/2012/08/24/the-new-evernote-smart-
notebook-by-moleskine/)

------
azat_co
You should definitely re-read it and if you a mac user there is dayOne app.

