Decision log using Jira and Automation — the Holy Grail of documenting decisions?
“Why did we do it?” — a question every sane leader dreads. It’s one thing to make a bad decision, but another to completely forget why you made it. It’s also a loss if you made a good one, but you don’t know about it or don’t know how to make it again. Given the fragile nature of human mind forgeting is inevitable if you don’t take notes.
Humans found a way to solve this problem and the solution has a name — decision log. Ship captains have been using them for centuries. Personal coaches recommend them today. Creating one at an enterprise level is a different story though.
There’s a problem of availability, problem of consistency, problem of quantity… that’s why for me finding a good tool for a decision log seemed like a search for the Holy Grail.
This article is the log book of my quest.
How to use this article?
The article is pretty long. It provides a holistic perspective on the search process, full explanation of the chosen option and a full tutorial on how you can set up a decision log yourself.
Naturally I’ll be thrilled if you read the whole article. However, I understand that you might not be interested in everything or you may want to come back to specific sections at different times with different needs.
So let me provide a summary of each section and a suggestion when to read it:
- The Problem
The first part provides an in-depth description of my thought process when looking for a solution with specific criteria I used. Read it if you’re looking for a solution yourself and you’re working on your decision model. - The Vision
This part breaks down reasons for chosing Jira and Automation for Jira as the solution. Read it if you are curious of what I envisioned as the perfect decision log. - The Solution
This part is a full tutorial of how to set up a decision log yourself. Read it when you have Automation for Jira installed. Basic knowledge of Jira administration might also be required.
Each section refers to a specific problem it solves:
3.1. Project setup — how to setup a project for your decision log.
3.2. Rule for prefilling description with a template — how to speed up documenting decisions and solve the consistency problem.
3.3. Rule for extracting labels from issue Summary — how to improve discoverability and organization of the decisions.
3.4. Rule that converts comments into decisions — how to drastically improve accessibility of the decision log where decisions are actually made.
3.5. Rule for decisions transitioning — how to remember about evaluating decisions.
3.6. Setting up a weekly newsletter — how to keep everyone in the loop.
I hope you find the article useful! If happen to use the same solution — please, leave a comment. It’ll be great to discuss new ideas with you. 🙂
Ok, let’s go! 🚀
1. The Problem
We finally experienced problems every company just has to experience:
- We forgot why we did some stuff.
- We forgot to check if the stuff we did actually worked.
- Some of use didn’t know that others did stuff.
- Stuff became to complicated to be decided upon in a couple messages.
Decisions were made on meetings, some were noted in documents, some in the comments, some dicsussed on Slack… Impossible to track.
Since we’re experienced fellows we already knew what to do about it — set up a decision log! The problem was… we never experienced a decision log that actually WORKEDD the way it was intended to work.
We already use, a now standard, but still a complex set of tools:
- Jira — for managing projects, tasks, visualising work,
- Slack — for on-the-fly communication,
- G-Suite — for collaboration on documents and e-mails,
- Miro — for brainstorming and visual context mapping,
And honestly, I believe it’s enough. It’s already challenging to onboard new hires into the ecosystem. So I reckoned, I’ll try to use one of the tools for the job.
Being responsible for making the decision log happen I thought, “what would the perfect decision log be like?” and came up with the following criteria.
Criteria for the perfect decision log
The perfect decision log should:
- Be available for every person on the team. No bottle-necks and restricted access.
- Be naturally integrated into our regular workflow.
- Be fast, in terms of jotting down a decision and refining it later.
- Have a system to track status of a decision process and notify about it.
- Allow for prioritization and setting due dates.
- Encourage and allow evaluating decisions.
- Convertable into a personalized, filtered feed.
- Allow for using templates.
- Be easily integratable with other tools.
- Offer some usage statistics.
So in general, the perfect decision log is less about editing and more about organising. As you can see, it’s a demanding set of criteria to meet. So let’s see — which criteria are met by our existing set of tools?
Rejected options
I share my thought process here. Scroll down for the “winner” section.
Confluence
A usual go-to in terms of decision logs you can find on the web. Confluence with its structured way of organising documents seems “the missing link” in our ecosystem. It’s easy to jot down a decision there, you can track status of documents and use templates. Creating personal feeds is also possible and setting up notifications is easily done.
However, for us the tool meant additional $5/user/mo., as it would be a new tool. Is it worth it? I doubt it. From my experience, editing documents in Confluence is very cumbersome. People still tend to use Google Docs, as they are more versatile and have better performance.
Using Confluence would also mean structural changes in the workflow.
I decided that I’ll go with Confluence only if the existing ecosystem turns out to be insufficient.
Google Docs
One of my favorite tools ever, with a great editing experience and easy interface. But it still lacks some features — templates that work out of the box, status and due date tracking and notifications were a must have for me.
Also, the content of a Google Doc is completely unstructured, so it would be hard to integrate it with other tools or look for usage statistics.
Miro
Miro (formerly RealTimeBoard) is an exceptional app. As our company grew, Miro became an essential tool for brainstorming, creative collaboration, day-to-day planning and organising knowledge. It is just great in so many ways!
It felt short only in 2 main regards — creating personalized feeds and fast jotting down decisions. Unfortunatelly with a great flexibility come great limitations. Visual and spatial nature of Miro makes the first load too slow. It is completely acceptable if you start a brainstorming session and you mean to spend a few hours working on a board. But after some time a decision log would be reeeally slow to load and, I assume, would stop being used.
Creating personalized feeds is also impossible in Miro, so everyone would need to load ALL decisions every time. Miro was out of the game.
Slack
Love it or hate it. My opinion is that it’s a great tool and most allegations against it actually regard company’s cultrure and people’s immaturity.
Still, it wouldn’t (and wasn’t) the best tool for the job. It’s really cool for jotting down thoughts and I think it would be easy to add decisions. However, we also want to document decisions that need to be made in the future. And long-term management of issues on Slack is impossible.
However, when I thought how easy it is to quickly write things on Slack it was so tempting to use it… But more on this later!
External tools
As I mentioned, I decided to first try to build a decision log using our existing set of tools. It didn’t mean though that I didn’t do my research. Some tools looked promising and inspired me with great ideas. None of them however was great enough to convince me to add it to our ecosystem.
Ok, that’s it for the introduction. Now you know my thought process, qualities of the perfect decision log and the options I rejected. It’s time to meet the winner!
2. The Vision
And the winner is… surprise, surprise — Jira!
Yeah, it was also kind of unexpected for me. Jira, while being a powerful tool, is known for its ridiculously complex interface, horrible performance (especially the cloud version which we use) and absurd UX shortages.
And yet, it was the winner.
The most important factors for me to even consider Jira were:
- It’s already used by all of our team and we spend a lot of time in this app.
- It’s great for tracking stuff over long time.
- It allows for prioritization, setting due dates and alerting.
- It has a lot of existing integrations.
- Tasks are a form of structured content so it’s easy to use it for statistics or aggregate it in a feed or something.
“But wait!”, you might say. “Didn’t you just listed a few criteria that Jira absolutely misses? Fast way to jot down a decision, for this matter? Please.”
Well, yeah. The three things Jira absolutely misses are:
- Description field templating,
- A fast way to jot down a decision
- Filtering can get tricky if you don’t build a good system from the beginning.
I wasn’t sure how to overcome these obstacles. And suddenly, out of nowhere, the solution emerged. I stumbled upon Automation for Jira and my project management life changed forever.
Jira + Automation for Jira = The Holy Grail
Automation for Jira is a powerful tool that let’s you create automated rules. A rule is a set of actions that launch under certain conditions in response to triggers. Trigger — conditions — actions.
I have coding background so I wouldn’t mind using programmatic interface for automation. However, the point-and-click interface not only makes it easier for me to create rules, but also allows others to create their own!
So how exactly automation solved my decision log problem?
The vision
Playing around with the plugin gave some idea of its capabilities, and soon I had a vision in my head. I assumed it‘ll be possible to:
- Create the Decision Log project with a workflow that resembles the decision’s lifecycle.
- Fill the Description field with a template IF it’s empty when the issue (task) is created.
- When the template is used, automatically assign the issues’ creators so that they remember they need to fill it.
- Analyze the Summary field (issue’s title) to extract #HASHTAGS and convert them to labels.
- Use the #HASHTAG labels to create personalized dashboard widgets with decision from the areas people are interested in.
- Analyze comments to all issues in Jira, so when someone adds a comment that starts with “Decision: “, it’s automatically converted to a issue in the Decision Log.
- When the new decision is created, the plugin can comment back on the original issue and link the two issues.
- With all these rules, it’ll be easy to create decisions from many contexts — Slack (using /jira extension), Todoist (using Zapier) or even via e-mail!
- Automatically set due dates for decisions in the Made column and use them to transition issues for evaluation.
The vision was so exciting! It took me a while (let me just say I saw the sunrise) but I implemented all of the above. Now, let me walk you through the ready solution, something you’re probably waiting for!
3. The Solution
3.1 Project setup
The project is fairly simple. I used a Kanban project without a backlog. Names of the columns reflect the statuses a decision may be in, so:
- In preparation, when the decision process leading person crafts the proposal for consultation;
- Waiting, for decisions that are temporarily blocked;
- In progress, the proposal is being consulted;
- Made, the decision has been made; The column only displays decisions updated in the last 2 weeks to limit the number of displayed issues.
- For evaluation, the decision’s consequences are ready to be assessed;
- Done, no more work related to the decision is required;
Fields that we use, besides the regular — summary, description, assignee, reporter — are:
- Summary — in Jira, it’s the issue’s “title”, usually under 250 characters;
- Description — can be long and formatted;
- Assignee — person who is next in line to do the work on the task;
- Reporter — who is considered to be origin of the task;
- Due date — when the decision should transition to the next status;
- Labels — for organising decisions around teams, products and projects;
So it’s pretty basic. Now, to the automation magic.
3.2 Rule for prefilling description with a template
The first rule I created was prefilling description if it’s empty on task creation. The template is our comprehensive framework for documenting desicions.
So when a new task (not subtask) with empty description is created in the Decision Log project, it’s filled with the following sections:
- Context and goal of the decision;
- Decision process — who makes the decision and how, who is consulting and who should be informed;
- Criteria;
- Available choices and their pros and cons;
- Final choice with substantiation;
- Necessary action points;
- Predicted consequences;
- Risks and how to manage them;
Then, there’s a section titled “Fill after observing actual consequences”:
9. Actual consequences;
10. Learnings;
An automation rule for this process is simple:
The rule will be triggered anytime an issue is created. First, the rule checks two conditions — if the issue was created in the Decision Log project and it’s not a subtask.
Then, if the description is empty, the Edit issue fields action is started. There I just chose to edit Description field and provided the content as seen on the screenshot above.
The second condition checks if the assignee field is empty. If so, the user who triggered the event is assigned. It is assumed she needs to do some work preparing the proposal and filling the decision template.
3.3 Rule for extracting labels from issue summary
One of my favorite apps ever is Todoist. And one of my favorite Todoist features is quick add, which allows to set a due dates, a project and labels by typing.
“Would it be possible to create a similar experience in Jira?”, I wondered. The answer is yes!
What’s the point of using Labels? Right now, most decisions regard everyone, but as the company will grow people won’t be able to track everything and they’ll have a need to filter their “decision feeds” down to several areas. Similar to watching certain hashtags on Twitter on Instagram.
And what’s the point of extracting them from Summary? You’ll see in the next section, “Rule to convert comments into decisions”. 😎
So, how to create a rule that extracts hashtags from an issue summary and converts them into Labels?
Let’s break it down step by step. The first thing we need is a trigger. In this case I decided I only want to trigger the rule on issue creation. When you edit an issue, it’s just easier to simply edit the Labels directly.
Then, there’s a condition, an If/Else Block that checks if there’s only 1 hashtag or more. My solution is rather naive (just check if the first # character is at the same place as the last # character), but the number of available functions was limited. The condition than is:
The reason I check it is that, for some reason, you need to provide one Label in a different format (text) than multiple Labels (an array). 🙄
In both cases the next step is an Action — Edit issue fields and I use the “advanced”, programmatic interface of the “Additional fields”.
For multiple Labels, the “Additional fields” content looks like this:
{
“fields”: {
“labels”: {{issue.summary.match(“(#[^\s]+)”).asJsonStringArray}}
}
}And for a single Label:
{
“fields”: {
“labels”: [“{{issue.summary.match(“(#[^\s]+)”)}}”]
}
}The last step is to remove the hashtags from the summary. So again, we use the Edit issue fields action, we choose summary and provide the following content:
{{issue.summary.replaceAll(“(#[^\s]+)”, “”).trim()}}Voilà!
I promised you the rule will be useful for the next one. I think you know why… 😏
3.4 Rule that converts comments into decisions
I mentioned that my favorite Todoist feature is Quick Add. Why? Because it allows me to document things without changing a context. I don’t need to switch between apps, don’t need to click anything, just use a keyboard shortcut, write something, hit enter and it’s done.
“What’s the equivalent for this in Jira?”, I thought. “When and where are the decisions actually made?”
Basically, I found 3 use cases:
- Decision is made in a “general purpose meeting” (e.g. weekly update) and doesn’t have a corresponding or related issue in Jira.
- Decision is a result of a dedicated discussion, that can be held online.
- Decision is made when discussing another issue.
In the 1st case, the decision just pops-up in a discussion and someone needs to document it somewhere anyway, so there’s a constant “context switching cost”. The Decision is documented and instantly transitioned to the Made column, as it needs no further discussion.
In the 2nd case, we start a discussion in the In progress column, every stakeholder weighs in and when the deciding person is ready, she documents the decision and sets its status to Made. No context switching — the discussion happens “within” the decision.
The 3rd case however is the one that bugged me. It seemed to me that many decisions may end up not documented. Just imagine — you discuss an issue (in a meeting or online), you come to a conclusion and now you need to change a project, create a task, link the decision to the original issue and leave a comment so everyone knows the decision was documented.
The context switching cost is really high. Especially, if there are multiple people in the meeting where every second counts. To make the Decision log a perfect one, we need to solve this problem!
We want to minimize the context switching cost, but make sure decisions are documented and linked to their original issues. What’s the natural place to document decisions when discussing an issue? A comment!
So without a further ado, let’s have a look at the rule that converts comments into decisions:
It doesn’t seem complicated but the devil’s in the details. The general flow is: whenever an issue is commented, check if the comment meets the criteria of a decision and if so — use its content to create a new decision.
The condition for recognising decisions is pretty simple — it just checks if a comment’s content begins with “Decyzja: ” (a decision in Polish).
The next part is to use the comment’s content to create a new task. The general pattern I introduced for a “decision comment” is:
Decyzja: [ISSUE SUMMARY (including labels)]
[ISSUE DESCRIPTION]So the first line is converted to a summary and everything from the second line to the end becomes the new decision’s description.
Let’s look at the action that creates a new decision.
There’s a lot to unpack so let’s start with the obvious:
- The new issue is created in the Decision Log project,
- The issue type is just a generic Task,
- Assignee is set to a user who triggered the event, so the commenter,
- Using the Linked issue field, the rule links the decision with the original task.
The tricky parts are the Summary and Description fields.
First, we need to extract only the first line of the comment. Next, we remove the “Decyzja: “ part which is just a trigger and we don’t really need it in the summary. Last, we need to trim the summary from unnecessary whitespaces and shorten it to 255 characters (limit for the Summary field in general).
The “code” looks like this:
{{triggerIssue.comment.last.body.match(“(Decyzja: [^\n]+)”).replace(“Decyzja: “, “”).trim().abbreviate(255)}}You can just copy it, but remember to translate the “Decyzja: ” keywords. 😉
Let’s move on to the Description:
{{triggerIssue.comment.last.body.replaceAll("(Decyzja: )([^\n]+)", "")}}The rule is much simpler — it just removes the whole line containing our trigger keyword “Decyzja: “ and uses the rest of the comment as a Description.
That’s it! 🚀
The coolest part is — this rule works perfectly with the previous ones! You want to instantly label the decision? Just use the hashtags in the first line that becomes the Summary. You want to use the decision template? Just don’t enter a new line, the description will be empty and the templating rule will prefill it!
Here’s an example of the rule in action:
That’s it! Simple, elegant, effortless. 🙌
3.5 Rule for decisions transitioning
The last rule I want to talk about is just a simple reminder for decision-makers that a decision needs to be evaluated.
Whenever a decision is transitioned to the “Made” column/status — its due date is set to 3 months in the future. Then, there’s a rule that daily scans all decisions in the “Made” column to see if any of them is due for evaluation.
Then it transitions all decisions due for evaluation to the “Evaluate” columns.
3.6 Setting up a weekly newsletter
The last thing, a cherry-on-top is the weekly newsletter that everyone from our company receives. The e-mail includes all decisions made in the last week.
You can set up one for your company by creating a new filter with a custom subscription.
The condition (status = Made and updated in the last 7 days) is not perfect, but unfortunaly Jira does not allow to use transition dates in queries. For us though, its accuracy was enough — every 1 in 10 decisions is sent twice, which is not a big problem for now.
To create a Subscription, click Details and then New subscription:
As you can see, the subscription can be easily modified to include or exclude certain labels . Every user or group can also create their own subscription with custom conditions.
That’s it, done! Congratulations! You’ve just made a huge step toward keeping your whole company up to date with the decisions that are made.
4. Summary
The question begs an answer — is this the Holy Grail? Does it magically make everyone happy? Of couse not. The Holy Grail is a myth and so is every tool that is supposed to solve all problems of human nature.
The solution still isn’t perfect. We’re experimenting with different ways to document decisions “on the fly”, when dicsussions are heated and meetings are already overtime. We constantly modify the template. We think about introducing the new ones.
That said, I feel like we’re the closest to the optimal workflow we’ve ever been. It felt great seeing decisions being documented by others. It felt great to evaluate my first decision after 3 months and really reflect on it. It feels great to see discussions under issues in different projects summarized with a decision comment. And finally, it feels great seeing that our team actually reads the logged decisions, discuss them and refer to them when working on their solutions.
Full evaluation is due in 3–4 months. Follow our publication to get notified when it’s published!
Until then, happy logging and congratulations on the length of your attention span! 👍
