
A Year of Developer Journals with jrnl.sh - carlchenet
http://rickcarlino.com/2017/11/27/keeping-a-developer-journal-with-jrnl-sh-html.html
======
jcrawfordor
I work in devops support for an under-development software project. At request
of the developers, I started keeping up a page in our wiki where, whenever
something broke that affected the developers, I just logged what happened,
why, and what I'm doing to prevent it happening again. The developers really
like this so they feel more in the loop about system issues, but it turns out
that I really like it because it's just really useful to have that log.

I don't want to keep the wiki page super busy, so I now keep a text file with
basically a much more verbose version of the same thing. What happened, what I
tried, what I eventually found was the root cause, how I fixed it, and what
I'm changing to prevent a repeat.

This has two big advantages. First, the obvious one is that when things act up
I can sometimes find details on a previous incident that I don't remember very
well. The second and I think even greater advantage, though, is that it forces
me to actually think seriously about the root cause and preventative measures
every single time, instead of just fixing the immediate problem and then going
on to the next thing in a rush.

~~~
karlding
That's basically what postmortems are! For those unfamiliar with the term,
postmortems are a written account of an incident, its impact, the actions
taken to resolve resolve it, root causes, and identifying any follow-up
actions to prevent the incident from recurring.

I think postmortems should be a valuable learning opportunity for the entire
company, and are by no means a punishment. In an organization that fosters
"blameless culture," this allows the organization to grow and to identify and
fix a weakness.

Google's SRE book [0] also talks a bit about this in the chapter about
Postmortems.

[0] [https://landing.google.com/sre/book](https://landing.google.com/sre/book)

------
zbentley
Utterly tangential, pedantic, and pointless pet peeve: people giving projects
a "file extension-ish" name (e.g. jrnl.sh) that _does not correspond to the
language in which the program was written_. It's a Python script, not a shell
script.

And yes, I know that the ".sh" probably refers to the fact that you use it
from the shell, not the implementing language. I said it was pedantic, didn't
I?

~~~
zeckalpha
It's not the name, it's a domain name: [http://jrnl.sh](http://jrnl.sh)

~~~
nichochar
Isn't the domain name the name though?

~~~
papa-whisky
The name is clearly just `jrnl`:
[https://github.com/maebert/jrnl](https://github.com/maebert/jrnl)

------
jjude
Similar to what is described, I keep a note of all errors I get while
developing. I started this practice after realizing how often I search for the
same error. Keeping a log of the errors and how I solved it saves me so much
of time. I blogged about it here: [https://jjude.com/flask-
errors/](https://jjude.com/flask-errors/)

Taking notes also makes me to conduct a thoughtful retro of what I have done.

------
atmosx
I keep an “engineering logbook”. I surely helps me put things into
perspective, I can’t say that it made me more “productive”, but it sure raises
awareness on issues and this is enough.

I prefer pen and paper by far, so I ordered a personalised notebook, it is
pretty good looking, most wouldn't touch it, but I'm planning on doing a
_collection_ of them.

By personalised I mean that it has my name on it and reads "Engineering
Logbook #1". I ordered this book from Stamford Notebooks[1]. No affiliation,
but they're I'm planning to ask some customisations when I order "#2".

[1]
[https://www.stamfordnotebooks.co.uk/](https://www.stamfordnotebooks.co.uk/)

~~~
vanzorn
Ran out of ink, did we? Leucchterm 1917 notebooks are awesome for logging /
bullet notebooks - especially the dot grid ones.

On the digital side, I was inspired to start using Org mode by following Sacha
Chua's map approach: [http://sachachua.com/blog/2014/01/tips-learning-org-
mode-ema...](http://sachachua.com/blog/2014/01/tips-learning-org-mode-emacs/)

~~~
atmosx
I used quite a few digital Journals. I still keep a personal, private one,
encrypted with GPG using vim and some basic automation via shell. I rarely
write there.

I like writing and have _a lot_ to write about but I prefer physical journals
by far... My handwriting is ugly too but I won't give up!

~~~
50CNT
Have you tried the palmer method[0] in regards to handwriting?

[0][http://palmermethod.com/](http://palmermethod.com/)

~~~
atmosx
Nope. Thanks for sharing, I'll definitely look at it, as I'm looking for ways
to improve both my handwriting and note-taking.

------
ppeetteerr
The tool is perhaps less important than the practice. I keep a journal with
entries for every time I am blocked by an issue I cannot solve in my head. The
process of writing it down, doing a pro/con list, working out the solution in
writing, etc, helps unblock it.

It's not so much about posterity as it is about unblocking issues and moving
forward in the most sensible way.

------
delsarto
Of course there's a million things to do this; I wanted something very
opinionated that simply turned a flat RST file that I keep every day (for
consumption by me) into some lightly styled HTML (for consumption by others)
so wrote rstdiary. I also keep a rough TODO list in there (it's either todo,
or it's done and goes into a daily entry).

[https://github.com/ianw/rstdiary](https://github.com/ianw/rstdiary)

[https://rawgit.com/ianw/rstdiary/master/sample/index.html](https://rawgit.com/ianw/rstdiary/master/sample/index.html)

Been working for me for about 4 years. Once you get a bit of a corpus, it
feels silly _not_ filling in some points for the day to keep the thing
rolling.

------
miobrien
This looks pretty cool. Installing it now.

More generally, I've been using Quiver for about a year. Highly recommended.
[http://happenapps.com/](http://happenapps.com/)

------
geraldbauer
FYI: A while a ago I published a plain text (standard) format for journals
called journal.txt. See
[https://journaltxt.github.io](https://journaltxt.github.io) Happy writing in
your journals.

------
otterpro
I keep a journal using text files and Vim, but it is a combination of notes
and journal. Instead of chronological order, I use text files based on the
subject/topic. For example, I have a text file (journal) just for "Javascript"
and another for "React". In fact, I even have notes on "journaling system", so
I'm updating it as of now, writing an entry about "jrnl.sh". ON each text
file, I'd write down what I learned, as well as snippets and URL of websites I
have encountered. I don't use "tags" that often, because sometimes I'd forget
the tags, or often it is hard to maintain them. I always have a Vim of
notes/journals open, and I use ctrl-p and grep to add/read/search entries
quickly. I think I might have about 400 (EDIT: over 1000) text files.
Everything is saved to a git repo. Certain notes are published automatically
as blog posts Hugo (by adding front matter, etc).

I also keep a personal journal in a traditional chronological order, which is
a single "journal2017.txt" file. I also recommend using private git repo, not
public, since it may contain some of your personal information, and private
thoughts.

For the non-technical person (i.e. not into Vim or Emacs), I'd recommend
Notational Velocity (nvAlt specifically) on Mac. I'd be using it, only if it
had vim keybinding. It syncs online to SimpleNote, and it makes journaling
really easy.

~~~
Diederich
Yes. I have been doing a simplified variant of this for over 20 years now.
(The git integration is newer than that :)

It's easy, functional enough and works quite well.

------
WA
I track what I worked on in a text file, and more importantly, what
_decisions_ related to my business I made on this day. If something comes up
that requires a bit of thought, I simply “discuss” it in free text form.

It works mostly as a brain dump. I rarely read older entries. But it’s good to
know that I could look things up later.

------
lars512
I began using a Github wiki this way. I like writing in markdown, and
scaffolded some basic navigation between days, weeks, projects and meeting
minutes. It’s been super helpful. I upgraded from billet journaling after
finding that a paper journal was not a good enough reference later.

~~~
sunsetMurk
care to share more about this setup? this sounds easy and like something I may
actually get myself to "commit" to doing regularly. heh

~~~
j_s
This would definitely help keep the contributions graph green!

------
purplecones
I love this! I use the Terminal and VIM every day and really enjoy tools that
fit within that workflow. I didn't even know about this project when I started
building a similar tool (with the same name!).

~~~
corobo
I have a relative path set up for my jrnl: "this": "./notes.txt"

which I've aliased: note=jrnl this

if I'm doing something that I get pulled away from it's a quick "note was
working on the flux capacitor in somefile" .gitignore the notes file as
desired

~~~
gknoy
Can you share more about how you set up relative paths? Is that a bash alias?

~~~
corobo
Sorry I completely missed that bit! The relative path part is set up in your
jrnl config usually ~/.jrnl_config

------
LVB
I wanted to journal more but struggled to remember to do so. A simple hack for
me was to take a page from Pomodoro an install a countdown timer (I happen to
use [https://itunes.apple.com/us/app/activity-
timer/id808647808?m...](https://itunes.apple.com/us/app/activity-
timer/id808647808?mt=12)). Every 30 minutes I'm reminded to capture what I've
been doing recently. Slowly I've been getting better at updating ahead of the
reminder.

------
tc7
Very cool.

I've been keeping a plaintext worklog at the day job to help with time-
tracking. Logging time in our system as I go is slow and painful, so I just
write it down daily and enter it all at end of week (month :|).

I have a file for each month (e.g. `2017-12-timelog`), it stays open all day,
and I just prepend entries like:

    
    
      Dec 1 Fri
      9 - 10: emails/updates
      - 11:30: BB-X10 make the list update async
      - 3:30: hacker news
      - 5: BB-X10 unit tests
    

I'm going to try jrnl for this use case -- feels like it'll be even simpler.

------
martinthenext
I've been developing something similar, but as a Telegram bot:

[https://telegram.me/daytobasebot](https://telegram.me/daytobasebot)

[https://github.com/martinthenext/daytobase](https://github.com/martinthenext/daytobase)

I found it easier to use telegram because it is available on mobile as well as
desktop, so I end up writing more things down.

Pretty great to discover jrnl.sh, validates my idea that this approach to
logging things can have wider adoption.

------
JustSomeNobody
I got started keeping a dev journal by logging bugs I fixed. I would document
the problem, recreate steps (if QA supplied none), what I thought was the
problem, what was the actual problem and finally how I fixed it. I also kept a
note of where in the source the bug was found. Sure, there are automated was
to do this, but we didn't use those at the time and, well, it led to a good
habit, so I'm happy.

Sadly, as much as I hoped it would, it hasn't translated into a good habit of
writing a personal journal.

------
sh87
I’ve been using Noguchi system fairly regularly, for general purpose notes and
I imagine it could be very effective in developer journals too. I like the way
Its described here, though I use plain text instead of MMD :
[http://www.literatureandlatte.com/forum/viewtopic.php?p=1592...](http://www.literatureandlatte.com/forum/viewtopic.php?p=15926#p15926)

And this is the key

> What I have found liberating is the concept of only have four tags

------
Cthulhu_
I noticed a colleague wrote down a basic work log every day, just a high level
approach to what he did during the day. I'm interested to try it myself, have
done so for a couple of days. I've used Day One, a (iirc paid) mac app, very
simple to use for quick blurbs. It also has a CLI, bit awkward to use maybe
(`dayone2 new "text here`).

~~~
j_s
Two weeks ago: Keeping a Lab Notebook |
[https://news.ycombinator.com/item?id=15704354](https://news.ycombinator.com/item?id=15704354)

Yesterday: Joplin – A note-taking and to-do app with builds for desktop,
mobile, terminal |
[https://news.ycombinator.com/item?id=15815040](https://news.ycombinator.com/item?id=15815040)

Both have recommendations for the process and tools.

------
cakeface
This is a great practice and I encourage all devs to try it. I just learned of
the jrnl tool but I use a very similar command line / text / file approach. I
have a few shell scripts for starting a new entry which I keep in a new file
within the directory. I also commit it all to a git repo.

~~~
DelightOne
Are you happy with it? What are your pain points?

------
ElijahLynn
I do this too! Not everyday, because some days are meetings or the problems I
am up against are not challenging. So I guess I only do it for challenges or
things I want to remember.

Anyways, highly recommend this, it is my rubber duck debugging method of
choice!

------
lemonberry
The comments and original post are great. I keep a directory called Core that
has project notes, code snippets and a journal. I recently started using VS
Code and a few extensions have really pulled my "system" together.

------
scadge
Is it capable to do basic formatting, like making lists, quotes etc? I see
there's a possibility to export into Markdown, but does it parse those
formatting elements or should I write them in MD already?

------
rickcarlino
Thanks for posting my article! I hope it is of use to the HN community.

~~~
FRex
The parts about no complicated file formats, ease of backup, keyboard only,
fast, easy to use, text only, etc. strike close to home for me because this is
what I also desired, to the point that I've written my own program to keep
various notes. It also had to be portable (Windows and Linux) because at the
time I had another weaker laptop that had to run Fedora and I wanted to use it
there too. I just couldn't find such a program, everything was bad, not
portable or 'rich' (aka images, styles, etc. aka needs mouse or has a complex
file format).

------
msaharia
How can I set the "default_hour" to present time in jrnl.sh when I don't
mention tomorrow, yesterday etc.? Looks cumbersome to write the present time
everytime.

------
sridca
I find that mind maps capture context and information better than linear logs.
Any one else use mind maps on a daily basis?

~~~
aryehof
In my case I just want to just capture information. Not think of
context/categorization/connections. Global search then makes anything from the
past instantly accessible, and I don't need to remember "how or where" I saved
it.

------
taternuts
jrnl is cool! I had a good time half-cloning it in node for practice/fun a
while back [https://github.com/Robert-Wett/journal](https://github.com/Robert-
Wett/journal)

------
submeta
This looks great. - Is there a way to prevent traces / entries in bash
history?

~~~
deivid
Put a space before running the command.

~~~
karlding
For bash users, that assumes that the HISTCONTROL [0] environment variable is
set to ignorespace (or ignoreboth).

[0] [https://www.gnu.org/software/bash/manual/html_node/Bash-
Vari...](https://www.gnu.org/software/bash/manual/html_node/Bash-
Variables.html)

------
memorythought
Does anyone know of a tool like jrnl.sh that integrates with GPG for
encryption?

~~~
Cthulhu_
Would it be hard to wrap it in a script that does that for you? I'm not
familiar with GPG but I can imagine a smart hacker made it so that you could
basically pipe it through.

~~~
memorythought
True, not particularly difficult. At the moment though I just keep GPG
encrypted text files if I handle encryption independently of jrnl then I lose
a lot of the value of it like being able to search by tag.

There was some discussion of including it here
[https://github.com/maebert/jrnl/issues/262](https://github.com/maebert/jrnl/issues/262)
but it looks like they might have decided against it.

------
pmatos
I wonder what's the difference between using this or org-mode...

~~~
corobo
One is the one you know and enjoy using, the other is not your preferred
method.

The world was beyond the emacs era and into the GUI editor when I started
developing so it's a hump I've not been willing to climb, jrnl works well for
me

~~~
zeveb
> The world was beyond the emacs era and into the GUI editor

Emacs _is_ a GUI editor (e.g.
[https://upload.wikimedia.org/wikipedia/commons/5/5a/Emacs-
sc...](https://upload.wikimedia.org/wikipedia/commons/5/5a/Emacs-
screenshot.png)), and the world _still_ hasn't progressed beyond it. I'd love
to be using something better than emacs, because it really is old & crufty,
but literally no other environment is as powerful, as extensible and as
pleasant to use.

~~~
eddieroger
> pleasant to use.

That is a matter of opinion, which is what the OP before you was trying to
point out. I know emacs, and use it as well when I'm in a shell environment,
but I prefer to use Atom in a desktop environment where I may be copying and
pasting from other apps. Pleasant is an opinion, which negates right and
wrong.

~~~
rpdillon
> where I may be copying and pasting from other apps

Is Atom better with copying and pasting certain kinds of content than Emacs?

~~~
gknoy
It depends on your Atom config and your Emacs config, I imagine.

When I paste things into Atom or Jetbrains' Webstorm, my javascript usually
gets auto-indented to The Right Place. Atom even did that when I _reordered_
lines, which was especially neat as I hadn't had Webstorm do it. This isn't
something that my Emacs will do. I'd be _very_ surprised if there weren't some
module, script, or Emacs configuration that I could use (or write) to get this
same behavior. After all, Emacs' "Tab to The Right Indentation" was something
that blew my mind years ago.

(Disclaimer: I have used Atom, but prefer Webstorm. I use Emacs, but only for
Git things and the occasional quick edit.)

~~~
tekacs
Not that you should have to know this, but for completeness' sake:

Out of the box in Emacs (with no config or extensions) you can simply select
the pasted region and hit Tab to reindent the whole area correctly (what you
called 'Tab to the Right Indentation').

So in total:

* C-SPC (Mark)

* C-y (yank/paste)

* C-x C-x (select to mark, essentially)

* Tab (indent)

([https://xkcd.com/378/](https://xkcd.com/378/))

Does what you'd like. This is all compositional, no magic here (and of course
you can bind this all to one key press). Naturally lots of people make this
auto-indent by default.

For me the most essential thing to know about those auto-indent modes is how
to temporarily turn them off (like `:set paste` in Vim), since I so often need
to bypass that behaviour for one reason or another (e.g. when resolving Git
merges - trying to keep the original formatting).

------
purplezooey
No Android support. Wish there was.

------
LeicaLatte
Very nice!

