DEV Community: Coding Friends UG

Macarons — Building a chat roulette app for Slack

Gabriel Reimers — Fri, 13 May 2022 14:29:28 +0000

Last year we tapped into building Slack apps.
Our first project was our decision record app Loqbooq. And while building a Slack app looks simple on first glimpse, it turned out to be very challenging. Especially user management and shared channels caused a lot of headache for us.

When we had finally achieved building and releasing our first Slack app, we thought it would be much easier to build another one based on that.

And so we did.

Within just a few weeks we build Macarons, a chat roulette app to connect teams.

We know there are already quite a few chat roulette apps for Slack like Donut, Snack or Hallway.

But we found those either too complicated, too expensive, or missing important features.

Macarons is simple to setup but at the same time comes with some neat features that make chat roulettes more fun for everybody:

🧁 Quick and Easy
Just add the Macarons app to a Slack channel and it will automatically pair off random members for (virtual) coffees.

🎰 Control the Odds
For each channel you can control how often and when chat lotteries happen, as well as how many people should be matched together.

🧊 Ice Breakers
Let Macarons get conversations started with predefined ice breakers or set your own custom topics for each round.

🏖 Take a skip day
Independent of a channels meeting interval, each user can always individually pause their participation or decide to only take part every other time.

You can try Macarons for free and we really appreciate any feedback:

macarons-roulette.app

Eating our own dog food – a year of decision logs (with Loqbooq)

Julius Peinelt — Wed, 29 Sep 2021 15:09:44 +0000

Loqbooq, our tool to document decisions in teams, is not our first rodeo. Frankly, rodeos aren't a good metaphor either. We have created and still maintain several app projects like Tincta – now in its 10th anniversary – and Wokabulary. But we have also been working in other teams on a diverse portfolio of products. So, we are more used to running marathons in a software development kinda sense. You know, staying long enough to ~~become the villain~~ see how your decisions worked out and hopefully learn from your mistakes.

Insufficient facts always invite danger (Spock)

To illustrate why writing down decisions is important, let's start with a quote by Admiral Hyman Rickover (who with his team designed the first nuclear submarine in just three years) from a speech he gave at Columbia University in 1982:

When important decisions are not documented, one becomes dependent on individual memory, which is quickly lost as people leave or move to other jobs. In my work, it is important to be able to go back a number of years to determine the facts that were considered in arriving at a decision. This makes it easier to resolve new problems by putting them into proper perspective. It also minimizes the risk of repeating past mistakes. Moreover if important communications and actions are not documented clearly, one can never be sure they were understood or even executed.

Not sure what else needs to be said about this, but have you ever been in the situation where you would have liked to simplify a system but you didn't know if the current state was due to rapid prototyping experiments or because of real business requirements and the people who knew had long left the company?

Anyway, of course people know of the importance of documentation, it's just not something that is overly fun. So indeed, in projects we’ve worked on over the years we did see some attempts at documentation. Sadly, most documentation emphasized the 'What' and left out the 'Why'. Additionally, the documentation was not always accessible to all team members. Comments in code, for example, are pretty invisible to most designers and managers.

Storytime!

Being aware of all those problems we set out to create a tool to lower the barriers to document all the 'Why' in projects while being approachable to all team members, too.
Naturally we started to use Loqbooq ourselves as soon as possible. In fact, the main development and reasoning behind decisions taken on the way while developing and releasing Loqbooq is documented in Loqbooq. Here is a short retrospective about the process and how it worked out for us.

It’s a… decision

Starting something new involves a lot of discussions, brainstorming and finally decision-making even before a line of code is written. For Loqbooq, we first spent a not insignificant time to narrow down the scope that left the final product usable but also would enable us to implement it in reasonable time. While originally Loqbooq was meant to be a Slack-only app, hoping this would reduce implementation time, it became clear this would limit the scope of addressable users too much.

A decision was made for the broader audience and we wrote it down in Nuclino, the knowledge base we use. I'm glad we did, as you will see later.

We also had to define our target user group, our assumptions about them and why we chose this group. Another very important decision for everything that comes afterwards.

Next, we asked ourselves which programming language, web-framework, database and hosting solution would enable us to quickly develop something functional.

Developers, being only humans, tend to involve some of their own ego when considering solutions for their tech-stack. Personal interests not seldom overrule sensible decisions. We wrote down our reasoning and crossed out alternatives with good arguments against them. This was probably the first time in this particular project where writing down the decision really forced us to be rational.

We’re not tooling around

Mind you, up to this point Loqbooq is far from usable. Instead, someone had to take notes or the main points from the discussion in Slack over to Nuclino, copy everything in a template and finally, if we weren't able to decide on the spot, remind everyone to add their agreement or proposals. How tedious to just document a little bit of 'What' and 'Why'. The same held true for looking up decisions taken in the past. Definitely something to improve.

The rubber meets the road

Fast-forward a few weeks and many decisions later, Loqbooq is finally usable and we decided on naming conventions for our domain model, colors for branding, and the fact that we support Slack's enterprise grid for the release. Reminders are sent out automatically and recording decisions happens right in Slack. This is directly reflected in the way we document the decisions: before, we only noted down big decisions with many considerations, like deciding on the whole tech-stack is all in just one decision. Now, even smaller things are documented or big decisions are split up. Something like our pricing model stretches over six different decisions, e. g. what happens with accounts that are late for payments, how long should the trial phase be, etc.

Around the same time it became clear that we would miss our aspired release date by at least a few weeks. The complicated (and frankly, insane) way Slack's enterprise grid is implemented from a data model perspective slowed us down and supporting all functionality with a web app suddenly felt like an additional burden.
Thankfully, our documented agreement on our domain language helped greatly navigating through Slack's and our own data model and their interaction.

But, what about all the work on the web app that was still waiting for us? We really wanted to release and time was ticking. So when I brought up the discussion in the team, questioning our direction, we quickly looked up the context and reasoning of the former decision about not just doing a Slack-only service. With that we were able to re-evaluate if we were still doing the right thing (spoiler: we released Loqbooq with a proper web app).

In hindsight, I'm glad we had the documentation of 'Why'. It enabled me to get rid of doubts and concentrate on taking the project forward, reducing the mental overhead significantly.

The same goes for our pricing model. Initially we went for a rather short trial phase and a one price fits all model. In the meantime we re-evaluated our decisions and since we documented the ‘Why’, we were even able to learn something. See our blog post.

One take-away to go, please

So now, after more than one year of consistently using a decision log, I have made some observations. Not all of them I merely attribute to the decision log itself but also to our practice to take decisions together. Which definitely is fostered by maintaining a decision log.

Reduction of recurring discussions. When we are unclear about why and what exactly we decided on a certain matter, we can now often just look up former decisions. And when we realized we are talking about the same topic twice, we create a new decision on it.
Increased feeling of ownership for the good but also the bad parts of the project. We took decisions together, but that means we also agreed together on where to take shortcuts.

Imagine starting at a project and soon enough you discover parts that feel messy and slow down development of new features. How soothing it would be to know why they are there. Maybe the project's scope changed, maybe some deadlines were too tight, maybe it's just some mess that needs a good cleaning.
So much learning. To learn you need a feedback loop, the faster you get feedback, the better. Sadly not all consequences become clear right after the action, to learn in that case, you need to be able to go back and look up the context of your decisions.
Ease of mind. Writing down and documenting decisions together with the considerations you and your team had frees up parts of your brain. Sometimes it just helps to be forced to really formulate a decision.
Improved communication. Since we decided together, we also had to discuss problems and possible solutions together. We had to actively argue about moving forward. As a very nice by-product, we also got rid of the feeling of others deciding over your head while you have to deal with the damage.
Additional documentation. Unlike with fast prototyping and other very short-lived projects, longer running projects need a certain documentation about intent, current available knowledge and context. Contrary to what is often seen, agile project management still involves having a plan (see: Rich Hickey), only the plan can be adjusted and changed. So, in long-living agile projects, it's not trivial to comprehend the reasons for the state of the project. In this case, decision logs can support or even replace requirements specification.

Not all glitter is gold

“Wait a minute”, you say, “you developed a Saas for decision logs. Of course it's all flowers, milk, and honey in your story.” Sure, I’m slightly biased and while I’m convinced Loqbooq helps with adopting decision logs and maintaining healthy logs with finer grained decisions, maintaining a decision log is still work and needs practice and learning. Even for us, not everything worked right away.

Sometimes we forgot to log decisions. Ultimately this is not a big deal, the next time you have a discussion about the particular topic, you will remember.
When in need of short-term approvals, outstanding decisions can block implementation. This happened mostly when we didn’t plan properly and needed some ad-hoc decisions and involved team-members weren’t available right away. In those cases, we went with some kind of majority but still leaving the decision open until the team members had a chance to review them.
Occasionally we had discussions about wording in decisions. While annoying at times, it also often pointed out different understandings that needed clarification.

It’s all about the seasoning

Decision logs are a very helpful tool for a more sustainable software development. Even if it's yet another thing to do, maybe even annoying at the moment, in the long run it helps to be able to go back and look at why things are as they are. But more than that, decision logs also foster communication and speed up the decision process by enforcing a written formulation. Last but not least, decision logs increase the sense of ownership if they are maintained together in a team.

Having a decision log is for project management a bit like having tests in your code base. It increases the sense of security in ever-changing, agile projects. Going back, having a look at the context of a decision and its reasoning can reduce disgruntlement over the current situation, too.
While technically you don’t need to use tools to maintain a decision log, they can help you lower the barrier of adoption and improve the quality of the log. As you can imagine, I can definitely recommend you to try out Loqbooq.

We as a team have found decision logs very beneficial and adopted them in basically all areas of our business.

Why we added a Free Plan for our SaaS

Gabriel Reimers — Sun, 29 Aug 2021 10:54:33 +0000

Early on we had decided that our SaaS Loqbooq should not have a free plan. After all, it is a service aimed at businesses not individuals.

We thought business customers are willing to pay for a service that saves them time and reduces friction. Now, two months have passed since we publicly releasing Loqbooq. And we found that assumption does hold true.

Still, this week, we introduced a free plan for small teams, including all features. What made us change our minds? Here is what we learned from our early adopters.

🤑 Our business model

Loqbooq is an app to record your project decisions and commit to these decisions as a team. We have a web app and a Slack app.

We are convinced that Loqbooq is a service that saves companies money. When you document your project decisions, your teams spend less time researching why things were done as they were done.
New team members can be on-boarded quicker as you have a record of all decisions on design, architecture or strategy, as well as the reasoning behind them.
And if your project involves multiple parties, it also reduces stress and discussions if stakeholders commit to decisions together.

Our customers consider Loqbooq a valuable tool that is worth paying for it.
And of course, we rely on paying customers as our business model. We do not sell our users’ data nor do we display advertisements — and never will.

💸 But then why add a Free Plan?

For us, offering a free plan is about organically convincing teams that Loqbooq is a useful and easy to integrate tool.

When we talked to our early adopters we learned that introducing new tools in a team can be a slow and complicated process. We often hear things like:

I really love Loqbooq. But I also need to convince my team.

We learned that it is often one or two individuals who see the need for a decision log in a project. The easy part for them is to find a tool for that (like Loqbooq). But the hard part is to convince their team to make the step to actually use a decision log.

We did already offer a trial period so interested teams could try out and experiment with Loqbooq before needing to enter a credit card number. Yet, this often was not sufficient.
Having created some sample decisions is just not as convincing as using Loqbooq as part of your actual daily work. And that is where we see the new Free Plan comes in.

🚀 Make it easy for early adopters

Now, a small group of early adopters within an organization can use Loqbooq with all features in their real projects for as long as they need it — for free!

The only limitations are that you cannot have more than three decision logs and can only have three reviewers on each decision. This should work out fine for small teams or startups.

Now, early adopters can play with Loqbooq and experiment with decision logs in a small project. They can take their time to integrate it in their work culture, project structure and other tooling they already have.

But most important: They don’t need to ask for budget to do a pilot project.

🙌 Spread to larger teams

Once a group of early adopters is convinced that Loqbooq actually suits their needs and improves their project management, they can start expanding the use to more or larger projects.

When they now pitch it to their teams, they have real world experience with the tool, making it much easier to win over more hesitant colleagues. And only then they need to upgrade to the paid Pro Plan for an unlimited number of logs and reviewers.

🎯 How it worked out

Well, we will only know in a couple of weeks or months. The downside of letting your users use your product for free up to some limits is obvious: it takes much longer for users to decide for a paid plan.