Start an Engineering Notebook

Camilla over at Winterflower argues that software engineers should keep an engineering notebook. That’s advice that everybody knows they should follow but that too many of us don’t. We’re busy and we think, “I’ll remember what I just did, I don’t need to write it down.” Of course, a little later we don’t remember and have to go through the pain of figuring things out all over again.

I keep a journal in which I record everything I do and discover but I’ve only been doing this for about 3 years. I really wish I’d started earlier. A good way of making it easier to get started and keep with it is to have a good system for recording things.

Of course, as an Emacs and Org mode user that means I have a built-in infrastructure for such things. One of the things that Emacs and Org mode provide is an easy way of retrieving information from your notebook. Org mode tags provide an excellent way of finding things. For example months ago I revised the way I compile Emacs (which can be a bit finicky on macOS), put it in my journal, and added the tags emacs and compiling. When I want to compile Emacs, I merely type Ctrl+c a m emacs:compiling to find all my journal entries with those tags. Even better, I have the commands in a code block so I can run them automatically by just typing Ctrl+c Ctrl+c in the block. That’s a real win over trying to figure out everything each time I compile a new Emacs.

There’s lots of examples like this, of course, and the more you put into your notebook, the more you can get out and the easier it will make things for you. Of you aren’t already keeping an engineering notebook, you should start. Or at least make a New Years resolution to start. I promise you, you’ll be glad you did.

Update [2017-12-13 Wed 14:48]: comilingcompiling

This entry was posted in General and tagged , . Bookmark the permalink.
  • Long ago after finding no value in blogging I fell in love with blogging
    because of Rebecca Blood.

    She shared the blogging model of “the notebook”. It is where I store my ideas,
    notes, lessons learned, and just about everything. I’m happy to share with all
    and write to satisfy myself. And it is all in Org-Mode.

    If you use Org2Blog then you already have done this albeit in separate files.
    But programs like ag solve and problems of keeping it in separate files.
    Publishing to WordPress instantly shares access to the rest of the non
    Org-Mode using world. If or when they want to cut over to Org-Mode then you’ve
    already got that ready for them too.

    It is a win-win.

  • NoonianAtall

    May I humbly recommend helm-org-rifle for searching Org notebooks as well. It is often faster than using agenda searches.

    BTW, another "notebook theory" that seems relevant is that of the "commonplace book." Org definitely fits that bill.

  • Bubbles

    Thank you for the blog post. I also find myself scheduling and writing only in emacs for 3 years now. I find that I don't look back on my old notes, except for work. I log alot of the project work I do for Uni, but i rarely end up doing a time analysis on it. While the purpose of logging seems to be the ability to go back, I think I just use it for the joy it gives me in the moment.

  • Win Treese

    This is utterly trivial, but your tag example above has "comiling" instead of "compiling". Completely obvious what you mean; just a bit jarring to read!

    • jcs

      Fixed. Thanks.