The #fyi comment system

A practical guide to leaving better comments

~4 years ago I started using the #fyi commenting framework at Keeper, inspired by Dharmesh and others.

Over the years, this system was embraced across the org and has gone through several iterations / extensions that enhance its usefulness.

This post documents the learnings.

The problem: not knowing “the question under the question”

Imagine you share a decision doc and get this comment:

Let’s say you’ve already thought about & discarded the idea. Now what?

Two options:

• Respond dismissively and risk looking like a naive bulldozer

• Freak out, drop everything, do research at the risk slowing down the project / decision unnecessarily

The right path depends on “the question under the question”. Is the CEO actually asking you to reconsider the whole proposal around reasoning models, or is it just a quick thought they typed up while on the loo?

Guess wrong, and you’re left looking stupid.

The solution

Now, the CEO can leave their quick comment without unnecessarily blowing up the proposer’s work-stream by tagging it:

• #fyi - the new reasoning models might be useful for this

• #suggestion - what about using one of the new new O1-style reasoning models for this? I want more functions in the org thinking deeply about leveraging the new tech, even if we decide not to do it in the short term it would be great to map out the pros / cons explicitly

• #recommendation - I think we should take a step back here and reconsider this proposal in light of the new O1-style reasoning models available. The risk operations team has seen tremendous success here - happy to connect you.

• #question - are you saying we’ll use the reasoning models to do this, or human labor?

Those are four very different messages and the required action by the receiver is much more clear.

Comment etiquette

In an ideal world, there are no comment threads at all because they introduce 3rd party latency and require constant context-switching.

A good comment etiquette is one where:

• If the comment is a #fyi, the responder just reads it considers it and then dismisses it.

• If the comment is a #suggestion / #recommendation then it just stays open until offline resolution.

To achieve this, the commenter has to:

• Make sure comments have sufficient context for the proposer to understand what is being said asynchronously. Taking that extra 30 seconds now can save you 10 minutes of context switching later. A quick example or scratchpad photo can go a long way here.

• Make themselves available for quick “jams”. Some things are just better to discuss live. Especially if both parties have context the other is missing. The key here is to eliminate all the boilerplate monologuing that can make meeting culture so inefficient. Just jump right into the disagreement - you should both already have context.

Learnings in practice

We’ve been versions of the system above for about 4 years now at Keeper. Some hurdles we encountered along the way:

• At the beginning, “action required by receiver” was a bit unclear and different people would react differently. I had to clarify several times and repeat myself before the process became smooth.

• Once established and clear, this system can easily become part of a performance management system. Someone who’s senior should have a lot fewer #recommendation comments on their proposals, vs a junior team member. All-stars should be able to “one-shot” more of their proposals where reviewers leave mostly #fyi’s.

• We used to mix up #fyi with #nit which have slightly different meanings. It took some clarification to fix this. I think #fyi is better because it more clearly conveys that the commenter doesn’t have too much conviction.

• Low performers may become reliant on comments in a way that’s unhealthy. They might make half-baked proposals, just to wait for the comments to roll in and do the thinking for them. This is not good, but I also don’t think it’s particularly unique to the #fyi commenting framework and is more of a perf management problem.