top | item 4448361

Keep a programming journal

171 points| feyyaz | 13 years ago |gist.github.com | reply

101 comments

order
[+] babarock|13 years ago|reply
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?
[+] aero142|13 years ago|reply
Speaking of pen and paper... When I was in college, Dijkstra had given a talk for the class a few years before his death, and my instructor passed out his notes. They were on a non-ruled piece of paper with perfectly drawn bullet points for each item. If he made a mistake, he would scratch the word out with a near perfect rectangle. The neatness and clarity was striking. I think it was the only handout in my entire time at the university that was hand written and photocopied instead of typed up on a computer... and it was from one of the most famous computer scientists.
[+] _pius|13 years ago|reply
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.

Agreed. Also relevant to this topic is Rich Hickey's talk on "Hammock Driven Development": http://blip.tv/clojure/hammock-driven-development-4475586

[+] kellishaver|13 years ago|reply
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.

[+] RossM|13 years ago|reply
I have a small (~A4) whiteboard for this reason. This method of writing pseudo-code to outline a solution is what caused me to learn Python as I found I was pretty much drafting Python code. I've found I produce much more efficient (and less buggy) solutions when I've stopped to think about them bit-by-bit.
[+] notJim|13 years ago|reply
> "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?

By this argument, do you also pay your bills manually by check at the end of each month? And book all your air travel by calling a travel agent?

There's nothing wrong with trying these things to see what advantage they have, but advocating the old ways of doing things purely because they're old seems more like religion than science to me.

[+] stephengillie|13 years ago|reply
I strongly encourage the "write it down" method of problem solving, aka the Feynman Algorithm. Making a text record is often a good idea, for remembering information as well as solving problems.

I disagree with using paper and a pen. Why spend time drawing these letters out when we can just type them? Is it just a strategy to force yourself to slow down and think about what you're writing? There's nothing magical about manually drawing letters.

[+] asynchronous13|13 years ago|reply
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.

[+] gmrple|13 years ago|reply
They taught me to have it signed, by myself and someone else every day.
[+] autotravis|13 years ago|reply
"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.

[+] getriver|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
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/

[+] pingswept|13 years ago|reply
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|13 years ago|reply
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.)

[+] FrojoS|13 years ago|reply
I looked for such a light markup language for a long time, but it also should work offline. What made me realize that this would be useful, was the bitbucket wiki. So, quite similar to your experience.

Than I found org-mode. We're happily together for over a month now ...

[+] roedog|13 years ago|reply
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|13 years ago|reply
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...

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

[+] imperialWicket|13 years ago|reply
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...

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|13 years ago|reply
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|13 years ago|reply
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.
[+] officemonkey|13 years ago|reply
Some people take notes to they better remember something. (I did that a lot in college. I would take notes to help me remember what I just heard.) For that kind of stuff, you just want to dump the data on paper.

There's other stuff that you'll write down because you're going to want to refer to it later. (For example, contact information, websites urls, things to put on a to-do list.) I came up with a simple set of margin icons ("@" for contact info, "w" for a www url, a checkbox for a to-do item, the date for an item for your calendar.

If you put them in the margin, then you can cross them off when you put them in your contact list, your calendar, or your to-do list.

You can extend this further with other margin icons. For instance, you can write "M" in the margin to identify meeting notes. or "Q" for a particularly good quote.

The key to note taking is to figure out how you would need the information later and improve the way you capture to support the way you consume.

[+] getriver|13 years ago|reply
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.
[+] JamesLeonis|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
> 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|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
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.
[+] tjr|13 years ago|reply
I have for several years used Papermate felt-tip pens, almost exclusively. I like the faux-fountain pen styling, and these pens require significantly less wrist pressure than ball-point pens I've used.
[+] davidcuddeback|13 years ago|reply
A lot of custom pens on Kickstarter use the Pilot Hi-Tec-C Gel cartridge. That pen seems to have a very loyal following. I've not tried it myself.
[+] aheilbut|13 years ago|reply
I really like the Pilot G-TEC-C4 - ultra fine (0.4mm) and don't smudge/bleed much
[+] nlh|13 years ago|reply
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|13 years ago|reply
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|13 years ago|reply
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.