Use a Decision Journal | Hacker News Reader

Use a Decision Journal

blog.trello.com

224 pointsingve38 comments

Also known as a Decision Record, as described by Russell Ackoff in many of his books. Another critical component to include in the Decision Record is not just the decision made, but also the other alternatives that were considered. The documentation should also describe why the other alternatives were not chosen.

Since we can only ever learn from our mistakes, a Decision Record helps us be honest with ourselves when we are evaluating things when they don't go as expected.

thank you for the hint. There are many works of Russell Ackoff. Could you recommend one of these for this regard?

I would love a recommendation too. This is the first time I've heard of decision journals or records

In every team i joined at later stages, it was an uphill battle to try establishing this. In the end i was always the only one maintaining it and management saw it as a waste of time. It is absolutely beyond me why decision journals are not standard. But i guess the source of the problem is that thorough evaluation of alternatives does not show immediate results to PMs and is against most devs "just starting to code" reflexes. Also if your choice is made by thinking "facebook also uses react and i already had to use it at my last job" it would be embarrassing to write this in a public document. (this is true for most EU projects, i really hope its different in the US)

> Also if your choice is made by thinking "facebook also uses react and i already had to use it at my last job" it would be embarrassing to write this in a public document

I agree that's not a very strong argument when making a tech choice, but still, it has more merit than a lot of resume-oriented-development I see: "we will use new tech X for this project because if we use the same old tech Y as we used for the last project, that will bore us, and there will be better job opportunities with other employers for the people working on the project if we gain experience in trendy new tech X". ... which is a pretty rational way for an individual to select tech, but not at all aligned with the interests of one's employer, or acting professionally & attempting to help one's employer make good decisions.

Actually both of the first arguments have a lot of merit, but can be phrased in a more professional way: "It's a well proven technology and many members on team already have experience with it so few deployment surprises expected and no training required."

And what's more important, even if you write something embarrassing like "i don't know of any other tool, but this tool seems to be good enough" in the journal, that is very useful information to know in the future, vs "we did thorough evaluation of 4 different libraries and found out the others does not support important use case X".

I cringe when I come across the aftermath of decisions that sorely needed a reality check from a "just starting to code reflex" prototype or POC. Unchecked by the compiler or the need to actually work, complex design documents tend to derail into fantasy worlds.

I want to read about what you ended up having to do after making contact with the real world, not what you thought you were going to do at the whiteboard stage.

I don't think he's saying you should write excessively before doing anything, just that enough context should be given to understand the decision at that point in time. At which point someone should start coding, and after real world experience changes the plan, that too could be added to the decision journal.

Which is why I love the idea of a decision journal! Currently we only really document the upfront designs. Ongoing logs would add even more value.

exactly

On the other hand I always get suspicious when a professional cannot describe me roughly what the road ahead entails — if someone is unable to explains this it usually means that they are either making it up as they go, that they never did this before or that they can't really communicate the things they do. And none of these are good signs.

Of course you cannot expect a hundred percent accurate picture with all the nitty gritty details beforehand, but unless you are working solo having clear goals is really important. Programming really is about the decisions one takes at each step and the domain specific knowledge one encodes within the project. That is why reflecting and documenting every once in a while really makes sense.

There's another benefit to having a decision journal, even if you do it alone and not as a team or company-wide effort: it reduces the time you have to waste fighting misinformation.

Companies bigger than a typical seed-stage startup usually come with an added level of bureaucracy. Products, tools, documents and others are usually created or pushed forward by different teams as a cross-functional effort. If you are the leader of such a project, the creator of a tool, methodology or document used by others, you will be expected to keep everyone in the gallaxy up-to-date with the details. Failing to do this will lead to certain personalities giving you a hard time. Suddenly people may start questioning your decisions in calls, emails and threads. You'll start wondering where all this skepticism comes from and will be forced to repeat yourself over and over again wasting valuable time. "Yes we did test whether to use X or Y architectures", "yes, we did test and consider this tool but it lacks feature Z".

I'm likely not alone in considering the above a less than ideal situation to be in. Having a well organized and detailed decision journal allows you to stop the noise almost completely. Also, as others mentioned, it gives your thought process structure, keeps you honest, committed and makes evolving a deliverable overtime easier.

I have a Google Sheets … sheet? … for this, and it's been handy.

I'm paper trading the stock market while I work on a couple of investment ideas (and still feel like I'm learning, so no real money yet). Every time I "buy"/"sell" a stock (logged in one tab of Google Sheets), I enter the date and the rationale I used when making the decision (logged in another tab of the same Sheet), as well as some context around the current state of the world. It's been useful already (a few months in), but will only get more useful, I believe, as I begin to note patterns in my own behavior.

This is such a simple, clever idea. I make what feels like hundreds of decisions a day (exaggeration but it feels like that sometimes) and I frequently finish the day exhausted and unable to remember anything.

I’m going to whip up a web app for this.

Please drop me a line when you're finished!

Will do! Do you have contact info somewhere? Twitter?

I think this is a great idea. How we see our decision making process in the moment is often vastly different than how we see our decision making process retrospectively.

Totally agree. And it’s also very easy to forget the context/why for any given decision, which makes it really hard to chain together a series of decisions to figure out how you got where you are...

Been meaning to spin up a blog every time I spent more than a certain amount of time researching and reviewing things and then decide on a first or second choice <anything>. I do sometimes find myself thinking about one or two elements of the other choices but when I try and recollect which one it was, or where I was struck by something... it can often be an inaccessible part of my recollection.

http://www.getoutcome.com

For software projects a viable alternative to a separate web app is to use the repo, eg with a commandline app like Nat Pryce's https://github.com/npryce/adr-tools

Maybe whipping up web apps that are redundant with existing software is contributing to your exhaustion...

There’s no joy in your comment

If it’s FOSS and easily self-hostable, that’d be even better.

I've recently ramped up work on something along these lines aimed specifically at personal finances (see my profile if interested... won't spam this thread). It's a spending journal which helps folks gain insight into their own spending habits and make better spending decisions. I've been using it as my own personal tool for years, and have recently (after being laid off) made it available for more folks.

What I found from my (currently) small circle of users, is that ease of use to enter the decisions was key. The SMS input has been key, and I'd recommend you consider it as a way to appeal to folks who would resist installing "yet another app with who knows what kind of data/privacy practices."

This is really great! Good luck with your project

Tangential: for me, the buzzfeed-esque GIFs make this post unpleasant to read. I couldn’t continue after a point.

Yes, they're really quite childish.

I stopped reading because I can't take articles full of gifs seriously; just content farm crap.

The author mentions decision fatigue and then cites that well-known judge study [1], implicating decision fatigue as an observed effect. However, the judges study probably isn't the best example of decision fatigue; see program_whiz's explanation [2] from another thread [3] on the judges study:

> Here is the refutation being referred to in the article, the article author did a poor job explaining it, and the reason to reject isn't "effect is too large", because the effect is real -- but this study explains it: http://journal.sjdm.org/16/16823/jdm16823.html

> 1. Prisoners are ordered by whether they have an attorney (so those going last in a session are self-represented)

> 2. Judges order prisoners often by "complexity of the case", so the ones taking most time are first (and therefore most likely to have a favorable decision, a short/easy case is probably a no-parole situation)

> 3. Statistically, the cases that gained parole take longer than those that don't, so even if they are random/normally distributed, then if one falls at the end, it will come back to the beginning of next session. A simulation shows that even with random ordering, you still get the same graph (because the long/complex cases that could be paroled tend to be moved to next session when the session is almost out of time).

> So after reading this, the graph means: Ratio of cases with a lawyer that can be finished in the remaining time in the session.

> Both values are decreasing as the session continues, so it produces a heavy down sloping graph that resets each session to some approximately random value (.65).

[1] Extraneous factors in judicial decisions | https://www.pnas.org/content/108/17/6889

[2] Here is the refutation being referred to in the article ... | https://news.ycombinator.com/item?id=14703990

[3] Impossibly Hungry Judges | https://news.ycombinator.com/item?id=14701328

Decision record journals can help teamwork, especially when the team also logs the decision alternatives.

Decision record templates are here: Template: https://github.com/joelparkerhenderson/architecture_decision...

I kind of disagree with having a decision journal. Because I don’t believe you have a set date or action that will mark a decision. And believing that it’s what make you procrastinate and delay things.

ADR is another form of Decision journal but for technical decisions.

for engineers, aka a design doc

The animated gifs make me need to write a decision journal to handle this article.

I read until I saw "As an article for Farnam Street recommends", and then I stopped reading.

What’s wrong with Farnam Street?

I think they were just letting us know how much of the blog post they read. It could have been that at the Farnam Street mention they suddenly realized they had cookies burning in the oven.

Reply on news.ycombinator.com