Diataxis Explanation

The Diataxis “Explanation” mode - oriented toward understanding rather than action, building a conceptual model for the reader.

Diataxis Explanation

Diataxis (from Daniele Procida’s framework) distinguishes four modes of documentation: tutorial (learning by doing), how-to (achieving a goal), reference (looking things up), and explanation (understanding why things are the way they are). The explanation mode is the one most often missing from technical writing - and the one that makes the other three make sense.

An explanation piece does not tell you how to do something. It tells you what something is, why it was designed this way, what tradeoffs were made, how it relates to other concepts. It is the mode that builds the mental model that makes how-to guides navigable. Without explanation, readers follow steps without understanding; they succeed when the steps apply and fail when the situation varies.

Explanation is oriented toward understanding, not action. A good explanation piece could be read with no intention of ever using the described system. It is interesting in itself.

Structural conventions

• Does not contain steps or procedures (those belong in how-to or tutorial)
• Does contain “why” reasoning: design decisions, tradeoffs, origins
• Builds concepts in order: simpler before complex
• Makes relationships explicit: “X relates to Y because…”

When to use

Concept docs, architecture explanations, “why does X work this way” posts, onboarding to a new domain, design system rationale.

When not to use

When the reader needs to accomplish a specific task right now. Runbooks, operational guides, reference documentation.

Pairs well with

friendly-mentor, candid, warm, blog-post-long-form

Often confused with

comparison-contrast: Comparison-contrast requires at least two subjects measured against each other. Diataxis explanation examines a single subject in depth to build understanding.

Tells

• Oriented toward understanding, not action - it could be read with no intention of ever using the system
• Contains no steps or procedures; those belong to how-to or tutorial
• Supplies “why” reasoning - design decisions, tradeoffs, origins - and uses “because” freely
• Builds concepts in order, simpler before complex
• Makes relationships between concepts explicit (“X relates to Y because…”)
• Aims to leave the reader with a mental model that makes the how-to guides navigable

Anti-patterns

• Slipping numbered steps or a “do this, then that” procedure into the explanation - Producing a completed action is the job of how-to or tutorial; explanation serves comprehension and loses its orientation the moment it starts instructing.
• Setting two systems side by side and measuring them against each other - Weighing two subjects on parallel dimensions is comparison-contrast, a confusable neighbor; explanation examines a single subject in depth to build understanding.
• Cataloguing facts and parameters as a dry reference with no why-reasoning or connective tissue - A flat list of what-is-true is reference material, another Diataxis mode; explanation earns its name by supplying the because and the relationships that build a mental model.

Failure modes

• Over-pursues complete understanding until the explanation balloons into conceptual scope-creep, surrounding the subject with so much context, history, and rationale that no graspable model ever crystallizes - Understanding is the goal, but a usable mental model is the deliverable; bound the explanation to the concepts that make this subject make sense rather than chasing every adjacent why.
• Indulges theory for its own sake, building abstraction on abstraction until the reader can follow each sentence yet cannot say what the thing is or why it matters - Tie the why-reasoning back to something the reader can hold - an example, an analogy, a concrete consequence - so the model lands instead of floating.

Instruction

Write in Diataxis explanation mode. Your goal is understanding, not action - do not include steps
or procedures. Build the reader's mental model: explain what it is, why it is designed this way,
what tradeoffs were made, how it relates to other concepts. Use the word "because" frequently.
Make relationships explicit. Build from simpler concepts to complex ones. The piece should be
interesting to read even by someone who never intends to use the described system.

Related

Pairs well with

Friendly Mentor, Candid, Warm, Blog Post (Long Form)

Avoid with

Operator

Often confused with

Comparison-Contrast

Examples

Should we adopt async-first standups?

Why Async Standups Work the Way They Do

An async standup is not a standup without the video call. It is a different kind of coordination mechanism, built on different assumptions about when and how information should move.

To understand why the distinction matters, it helps to understand what a standup is actually trying to accomplish. The daily standup has two functions that usually coexist in the same meeting without being separated: status visibility (who is doing what, what is blocked) and team cohesion (the daily ritual of shared presence, the sense of a team operating together). Synchronous standups do both at once because everyone is in the room at the same time. Async standups separate them.

The status-visibility function works differently in async format because information becomes persistent and addressable. In a synchronous standup, a blocker mentioned verbally reaches everyone in the room, but only for the duration of the sentence. The person who can resolve it must remember it, and the people who might have the same problem next must either have been present or get told separately. In an async channel, the same information is posted, searchable, and accessible to anyone on the team regardless of timezone or work schedule. The blocker reaches the right person not because they were present but because they are mentioned directly.

The team-cohesion function does not transfer to async in the same way, and this is why async-only teams sometimes feel fragmented. Daily synchronous standups create what anthropologists call “phatic communion” - interaction whose function is social bonding rather than information transfer. “How’s it going?” is not a request for information; it is a gesture of acknowledgment. Async updates can approximate some of this through informal additions to the update template, but a Slack thread is not a room. The teams that sustain cohesion in async-first environments almost always supplement their async standup with a different synchronous ritual - a weekly working session, a monthly retrospective - that exists specifically for the cohesion function that async cannot provide.

The reason async standups often produce higher-quality status information than synchronous ones is cognitive: writing forces more clarity than speaking. A person who says “working on the auth refactor” in a standup has technically satisfied the format. A person writing the same update often notices the vagueness before they post it and adds the detail that makes it useful. The act of writing creates a moment of reflection that verbal turn-taking does not.

How to start a morning routine

Why Morning Routines Matter

This document is an explanation. It is oriented toward understanding rather than action. If you are looking for steps, see the how-to. If you are looking for a recommendation, see the executive summary. The goal here is to give you a clearer mental model of what a morning routine is doing, so that any later decision about whether and how to adopt one is informed.

What a morning routine actually is

A morning routine is commonly described as “the set of things you do in the morning.” That description is true and unhelpful. A more useful definition is structural: a morning routine is a pre-committed sequence of actions that sits between waking and the first reactive demand of the day. Its function is to insert a buffer of deliberateness into a window that would otherwise be filled with reactivity.

Two pieces of that definition are doing the work. “Pre-committed” means the sequence was decided before this morning, so that this morning’s tired brain does not have to design it. “Buffer” means the routine is not the work itself; it is the space between the alarm and the first thing that demands a reply.

The problem it is solving

The conditions of modern adult life produce a specific morning failure mode: the first hour of the day is colonized by inputs from elsewhere. Messages, news, schedules, and other people’s priorities arrive immediately and at scale. In the absence of a routine, the brain answers them in the order they arrive, and the day takes its shape from that order. By the third or fourth response, the day is no longer being chosen; it is being assembled by whoever sent the loudest input first.

A morning routine intervenes in this sequence. It puts something between waking and the first incoming demand. The content of that something matters less than the fact of it.

Why this is not a productivity question

Morning routines are often categorized as productivity practices. This framing is misleading. A morning routine is closer to a governance practice. It is not about doing more in the morning. It is about establishing, each day, that the day will be governed by something other than the inbox.

The distinction matters because productivity-framed routines tend to optimize for output (workouts completed, pages written, tasks finished) while governance-framed routines optimize for alignment (the day’s shape matches the person’s actual priorities). The two often look similar from the outside but produce different experiences from the inside.

How it compares to alternatives

There are other ways to address reactive mornings. Email schedulers, focus-mode apps, and aggressive calendar blocking all attempt to manage the same problem from a different angle: by changing what reaches you, rather than by changing what you do first. These tools can be effective, but they share a vulnerability. They depend on systems that the day’s chaos can disable. A locked phone in another room is harder to disable than a software setting, and a routine you have practiced is harder to disable than a phone in another room.

The morning routine is the lowest-tech option. That is part of why it tends to outlast the alternatives.

What it does not do

A morning routine does not protect you from a hard day. It does not guarantee any particular performance. It does not, by itself, make a person more disciplined, more virtuous, or more focused. What it does is make those qualities more accessible by ensuring that you arrive at the day rather than waking up already inside it.

That is a smaller claim than morning routines are often credited with. It is also the claim that holds up.

How to choose between Postgres and DynamoDB for a new service

Diataxis Explanation on: Choosing between Postgres and DynamoDB

This piece is not a how-to. It does not walk through configuring either database, nor does it tell you which one to pick for the Lattice Notify notification system on Wednesday. The goal is conceptual: by the end, you will understand why the choice between Postgres and DynamoDB is harder than it looks, and why that difficulty is structural rather than accidental.

Why these two databases represent two different theories of storage

Postgres is a relational database. Its design intent is to model rich relationships between entities and to answer arbitrary questions about those relationships through SQL. The schema is rigid up front; the queries are flexible later. DynamoDB is a key-value (and document) store. Its design intent is to serve one well-defined access pattern at predictable latency and unlimited scale. The schema is loose; the queries must be designed up front. These are not two products competing on the same axis. They are products from different worldviews about what a database is for.

This matters because the Lattice Notify notification system has, at launch, exactly one access pattern: “give me the recent notifications for user X, ordered by time.” That is the kind of access pattern DynamoDB was built to serve. But Lattice Notify also has analytics, billing, and product-surface queries that span the user, the notification, the workspace, and the integration. Those are the kinds of queries Postgres was built to serve. Neither database is bad at the wrong job; both are designed for the right one.

Why familiarity is a real engineering quantity, not a feeling

There is a temptation to treat “the team knows Postgres” as a soft consideration that should be weighted lightly because real engineers can learn anything. This is a misunderstanding of what familiarity is. Familiarity is the property that the alerts trigger on the right thresholds, that the runbooks reflect the actual failure modes, that the on-call engineer has seen this exact stack trace before and knows what query to run. Familiarity is, in effect, a body of cached knowledge that was paid for in past incidents. Discarding it has the same cost as paying for it again.

This is why the four-person on-call rotation at Lattice Notify is a load-bearing consideration in the choice. The rotation is the body that holds the familiarity. Adding a second database does not add a small new system; it bifurcates the body that holds the operational knowledge.

Why “scale” is the wrong word for what is being decided

The Postgres-versus-Dynamo conversation often gets framed as a scale question: Postgres handles small workloads, Dynamo handles big ones. This framing is wrong because Postgres handles very large workloads in production at companies much bigger than Lattice Notify. The real distinction is not scale but the shape of growth.

Postgres scales by deliberate engineering interventions: read replicas, partitioning, sharding. Each intervention requires a team to plan it, execute it, and operate it. DynamoDB scales by configuration: you increase the throughput setting and the system grows. The difference is not how much volume each can handle but how much engineering work is required per unit of growth. For a team facing 500K events/day at launch and a possible 5M events/day in twelve months, the question is whether the team has the engineering bandwidth for the deliberate interventions Postgres would require, or whether they need the property that the database scales without their attention.

Why the decision is bound to a probability, not a number

A common mistake in storage decisions is treating projected volume as if it were known volume. Lattice Notify’s “10x growth in twelve months” is conditional on the Slack-partnership deal closing. That deal has a probability, not a certainty. A correctly framed decision uses the probability: the expected operational cost of each option is the sum of the costs in each scenario, weighted by the probability of that scenario.

This is why Priya’s request to the CRO for a probability estimate is not a procurement step. It is the input that converts the architectural choice into a decision under uncertainty rather than a guess about the future. Without the probability, the team is choosing between databases. With the probability, the team is choosing between theories of how to absorb risk.

Understanding this is the point. Whether you choose Postgres or Dynamo on Wednesday is downstream of whether you have grasped what the choice is actually about.

Telling stakeholders a committed feature is being cut this quarter

Why Insights Moved to Q1

The Insights dashboard is moving from Q3 to Q1. Before we get to what that means for you, it is worth explaining why this kind of shift happens - because the reason is structural, not a symptom of poor planning.

Why migrations consume roadmaps

A billing-system migration is a different kind of work than building a product feature. Features can be scoped, parallelized, and shipped incrementally. Migrations cannot, because their correctness depends on a single moment: the transition from the old system to the new one. Until that moment, both systems must stay synchronized, which means the migration consumes engineering attention continuously, not just at its scheduled end. When a migration overruns - and billing migrations carry a high rate of unexpected complexity, because billing logic accumulates business rules over years that are only fully visible when you try to change them - the overrun is absorbed by whatever was next in line.

Insights was next in line.

Why “half-built” is not an option

A dashboard is not a report. A report delivers a fixed set of numbers; a report with half the numbers is half as useful. A dashboard, by contrast, is a system of navigation: it promises that you can explore your data, track what you care about, and trust that what you see is the whole picture. A half-built dashboard breaks that promise not by showing fewer numbers but by making the numbers it does show untrustworthy. Users cannot distinguish which gaps mean “not yet built” from which gaps mean “this data does not exist.” The tool becomes a liability because it creates confidence where confidence is not warranted.

This is why the team is shipping a CSV export as a bridge instead of a partial dashboard. The export is honest about what it is: raw data, delivered so you can analyze it in a spreadsheet or BI tool of your choice. It does not pretend to be Insights. It does not make navigational promises it cannot keep.

What this means for Q1

Insights in Q1 carries the same scope that was committed for Q3. The design has not changed; the timeline moved because the engineering capacity needed to build it properly was consumed by the migration. When the migration completes - which it will, because migrations have a defined end state unlike feature work, which can expand - that capacity returns to the roadmap and Insights becomes the first priority.

The CSV export in September is not a substitute for Insights. It is a carrying mechanism: something that gives you access to the underlying data while the full experience is built on a foundation that is now stable.

Getting a new engineer productive in their first two weeks

The two-week onboarding structure is not a schedule; it is a theory of belonging.

New engineers rarely struggle because they lack access to the repository or have not been shown the deployment pipeline. They struggle to thrive because no one explained why the team works the way it does, which means they must infer every decision from its visible artifacts alone. A codebase without context is archaeology, and archaeology is exhausting.

The first priority is removing friction rather than transmitting knowledge, because a new engineer who cannot get her environment running cannot learn anything else. Access and tooling come first not because they are the most important things, but because they are prerequisites for everything else. Without them, even the best orientation collapses into theory with nowhere to land.

Orientation - the reading, the walkthroughs, the architecture conversations - matters because it gives Priya a map she can refer back to. But a map is not the territory. She will not know which parts of the codebase are stable and which are contested, which decisions are settled and which are perpetually argued, until she has moved through the territory herself. This is why pairing on a real change belongs in the middle of the two weeks rather than at the end: it converts the map from abstract to navigable.

The choice of first change matters for reasons that are not purely technical. A change that is too small signals that the team does not trust Priya with anything real. A change that is too large risks a blocked first week, which generates anxiety rather than momentum. The right first change is one where the scope is bounded but the consequence is genuine, because genuine consequence is what makes the work feel like membership rather than a test.

Belonging and function are related, but they are not the same thing. A new engineer can be fully functional - able to access systems, understand the codebase, respond to incidents - and still feel like a visitor. Belonging emerges from a different source: being trusted with something real, being included in a decision, having someone explain the unwritten reason behind a written rule. This is why the human side of the two weeks is not a supplement to the plan but a dimension of it. The plan fails if Priya ships a change and still feels like a guest.

The on-call rotation sits at the intersection of function and belonging because of what it signals about trust. Being added to the rotation before Priya is ready is overwhelming; being excluded indefinitely is isolating. The right answer is not a date but a conversation - one where she and the team agree on what readiness actually means, which is itself an act of inclusion.

Writing to thank a mentor who shaped your career

The thing about what you did, Dana, is that I did not understand it at the time. That is not a complaint - the understanding would not have been possible at the time. You put me forward for the Meridian project in my second year, when I still thought competence and readiness were the same thing. I learned, eventually, that they are not.

Competence is the accumulation of past experience. Readiness is confidence that past experience will transfer. The two travel together, which is why they are so often confused. But a person can be competent for something they have never done before, because competence is not a lookup table of things tried; it is the underlying capacity that makes trying productive. The reason you could see that I was ready before I could see it myself is that you were reading my capacity, not my history.

This matters because what you gave me was not a project. What you gave me was evidence that my capacity was real - evidence I could only receive by using it. The logic is circular in the best way: the thing that would prove I was ready was the same thing I needed to be ready for. You broke that loop by betting on me.

What it cost you is something I only grasped last spring, when I did the same for Priya on the Atlas rollout. Staying close without taking over is not a passive position. It is active restraint applied continuously, because every instinct pulls toward resolution. When Priya stalled on the stakeholder mapping, I knew what the answer looked like. Not stepping in meant tolerating the possibility that she might not find it, or might find a worse version of it. Patience in that mode is not patience in the colloquial sense of waiting calmly. It is holding a posture under repeated pressure to drop it.

I did not understand, until I held that posture myself, why you had to hold it. The gratitude I carried for a decade was real but incomplete because I was grateful for the outcome - the confidence I built, the reputation that followed - without understanding what the outcome required of you. Now I understand the tradeoff: you absorbed the risk of my failure so that the cost of my learning would fall on me and not on the project. That distinction is the whole of it.

What you made possible is something I cannot return to you directly. But I passed it to Priya without fully knowing I was passing it, which is the clearest sign I can offer that what you did worked: it became the way I think.

Reflecting on keeping a discipline of rest

Why a Day of Rest Works the Way It Does

This is an explanation, not an instruction. If you are looking for a method or schedule, this is not it. The goal here is a clearer model of what a day of rest is actually doing, so that the experience of taking one - and failing at it, and trying again - makes more sense.

What rest is not

Rest is not the absence of work. This matters because if rest were simply the absence of work, you could rest by doing less work, or by checking the phone less often. Neither of those things is rest, and understanding why is most of what you need to understand about rest itself.

Work is a particular orientation to time. In work-mode, every hour is potentially accountable. Attention organizes itself around what is incomplete. This orientation is often energizing, but it colonizes a day entirely if it is not interrupted by something with a different structure.

Why you cannot half-rest

Rest has a different structure, and because it has a different structure, it does not mix with work in small doses. The pull to check one more thing is strong because that check reactivates the incomplete-horizon. Once the incomplete thing is in view, work-mode returns. Not partially. The mode is binary, or close enough to binary that the difference does not matter in practice.

This is why a day of rest requires a real boundary rather than a softer reduction in effort. The boundary is not a moral position about screens or schedules. It is a structural requirement. The thing being protected - orientation toward presence rather than progress - cannot coexist with even a modest instance of forward-accountability.

What the anxiety means

When rest produces anxiety in people who are used to measuring days by output, that feeling is accurately reporting something real. It is not evidence that rest is wrong. It is evidence that the mode-shift is real - that something has actually changed in how time is being held. Work-mode has detected that accountability has been suspended, and it registers that as a problem because accountability is what it is for.

The anxiety fades not because rest convinces you it is productive, but because the nervous system eventually accepts that incompleteness is permitted to sit still. Rest does not have to be justified by its outputs.

What rest returns and why

The clarity and steadiness that appear in the surrounding days are not mysterious once this model is in place. A week oriented entirely toward forward-movement has no position from which the movement itself can be evaluated. Rest is not outside the week; it is the one position in the week from which the week becomes visible.

This is the relationship that people who practice consistent rest report but often struggle to explain: the day does not feel like lost time in retrospect, even though it felt exactly like lost time while it was happening. It feels, eventually, like the point around which the other days organize. This is not a reward for discipline. It is rest doing what rest is for - because only from stillness can you see what the motion is aimed at.

Marking a long-serving colleague's departure

Most careers are described as trajectories - up and to the right, accumulating titles as they go. Howard Albrecht’s twenty-six years at Meridian make sense only once you set that frame aside and understand a different principle: depth and trajectory are not the same thing, and the people who choose depth are undervalued precisely because their value is invisible until they leave.

Howard spent nearly all of those twenty-six years in the same role, not because he lacked opportunity but because staying was a choice with its own logic. A career that moves laterally every few years accumulates breadth - exposure to many situations, relationships across many teams. A career that stays put accumulates something different: layered knowledge of why this system works the way it does, what was tried before, which approaches look sensible on paper but fail at the friction points of this particular team. These are not interchangeable. The second kind of knowledge cannot be onboarded or summarized in a handoff document, because it lives in pattern recognition built across thousands of small decisions over many years.

This is why Howard became the person everyone called. Not because he was the most senior, but because he held the conceptual model that made the work make sense. When a crisis arrived, calling Howard was not sentiment - it was because he had already seen the shape of this problem, or something adjacent enough that his read on it shortened the diagnosis.

The reason this kind of tenure produces mentorship almost by accident is because depth of understanding is transmissible. Howard could explain the why, not just the what. That difference is why several careers here carry his fingerprints: he gave people the conceptual structure to reason from when the situation varied, which is the only kind of mentorship that travels with you.

What the organization loses now is not his output - it is the mental model he carried. Institutional memory has to be rebuilt from the traces he leaves: the documentation that will never be quite complete, the colleagues who absorbed pieces of his understanding, the patterns that will occasionally confuse people who lack the historical context to read them. This is not a failure of succession planning. It is the nature of knowledge that lives in a person rather than a system.

That is worth naming clearly. Howard did not just do a job well for twenty-six years. He held a mental model that made a section of this organization coherent, shared it whenever sharing it was useful, and because he was not managing up or building visibility, it happened quietly - which is part of why it is so hard to quantify now and easy to underestimate.

Marking the team shipping a hard, long project

The Checkout Rebuilders: What Made This Hard

The team that rebuilt the checkout flow over the last fourteen months did not write software from scratch. That distinction matters more than it first appears, because building new things in empty space is a different category of problem from replacing something that real customers depend on every hour.

A greenfield build fails quietly. Bugs surface in testing or in early traffic, and the cost of learning is bounded because nothing depends on the new thing yet. A live-system replacement works differently: the old system is simultaneously your safety net and the constraint that shapes every decision the new system must respect. Priya Vasquez and her team were not solving a checkout problem in isolation; they were solving it while the existing flow processed transactions that the business could not afford to lose, for fourteen months, without interruption.

This is why the parallel-track structure was not a conservative hedge but a structural necessity. The old flow had to keep running because customers had no alternative. That requirement meant every architectural choice in the new system had to be validated against what the old system could not do - which required understanding the old system’s failure modes well enough to document them. In many cases, those failure modes had never been documented, because the system predated the current team.

The near-misses in months six and eleven were not accidents that nearly derailed the project. They were the moment the project became legible. A near-miss reveals where the real complexity lives, and in both cases the team diagnosed the weakness and rebuilt the specific path that had exposed it. This is exactly why the final rollout held under peak traffic: the system had already been tested against the conditions that would have broken it. The slipped launch dates carry the same explanation. The team twice recognized that the system was not yet the thing it needed to be, and declined to pretend otherwise.

Cart abandonment is a lagging indicator because it measures the downstream effect of friction that occurs much earlier in the flow. Marcus Chen’s work on the session-state layer removed three round-trips that the old architecture had accumulated over years of patching. Customers will not know this happened. They will only register, in some wordless way, that finishing the checkout felt less like work.

The achievement is not that the team shipped. It is that they held their nerve long enough to ship the right thing.

Arguing a public position on return-to-office

The return-to-office debate stalls because both sides are partly right, and neither has a clear account of why. Office-first advocates are correct that in-person time builds trust and accelerates unplanned collaboration. Remote advocates are correct that distance enables focused work, widens the talent pool, and returns commute hours to employees. The debate looks like a binary choice because the underlying mechanisms are not clearly stated. Once they are, the right shape of a policy becomes easier to see.

The office works because it lowers the cost of serendipity. Trust and unplanned collaboration do not happen because people share a floor plan. They happen because people accumulate unscripted contact - the exchange that catches a problem before it becomes a formal ticket, the conversation that reframes a disagreement because both parties are in the same room. Physical presence increases that density because it removes the friction required to initiate contact across distance. You do not have to wonder whether the other person is available; you simply catch them.

Remote work operates through a different mechanism. Deep focused work - the kind that produces a careful design or a thorny patch - benefits from long uninterrupted stretches. That quality of attention is harder to sustain in an open office than at a desk where you control the environment. Remote work also decouples skill from geography, which is why it widens the talent pool, and it eliminates transit time, which is why it returns meaningful hours to employees. These are structural consequences, not perks.

A deliberate hybrid is the right posture not because it compromises between two camps but because in-person presence and remote flexibility serve different functions. The office is a serendipity accelerant. Remote time is a focus amplifier. Treating them as competing goods is the error that makes the debate intractable.

Anchor days matter for a specific reason: serendipity is a collective action problem. If everyone selects different days independently, the density that makes in-person time valuable disappears even if the office is nominally open. Shared anchor days work because they synchronize the people who benefit from encountering each other. The remaining days can be flexible because focused individual work does not depend on co-location.

The office-first objection - that remote work erodes culture - is partly right but misdiagnoses the cause. Culture erodes from infrequency of meaningful contact, not from distance itself. The fully-remote objection - that mandated presence wastes time - also has force but aims at the wrong target. The waste is in presence that serves no collaborative purpose. Both objections dissolve once the underlying structure is visible: the right amount of in-person time is the amount that maintains the density of contact that collaboration requires.

Announcing a new product to an outside audience

Small teams do not struggle to collect feedback. They struggle to make sense of it.

Feedback arrives through the chat tool, the ticket tracker, support emails, user interviews, and sales calls - each channel making perfect sense to whoever manages it, and each channel largely invisible to everyone else. A support person has triaged every complaint about the checkout flow. A product manager has read the strategic interviews. An engineer has lived inside the bug queue. None of them are wrong about what they have seen. They simply hold different fragments of the same picture.

This is the problem Tidemark was designed around. It is a feedback-to-roadmap tool, and understanding why it takes the shape it does requires understanding why the gap between “collected feedback” and “shared roadmap” is so hard to close.

The instinctive response to scattered feedback is a spreadsheet. The spreadsheet solves the collection problem: you can pour every piece of feedback into one place and no longer worry that something is hiding in a separate channel. But the spreadsheet does not solve the ranking problem - deciding what matters most - because ranking is a judgment that requires shared context. And it does not solve the sharing problem, because a spreadsheet that one person maintains is, functionally, just another private channel.

Tidemark’s architecture is a response to one observation: the ranking problem and the sharing problem are the same problem. Teams fail to align on priority because they are reasoning from different subsets of the evidence. Once the evidence is pooled and visible, disagreements about priority become specific and tractable rather than general and recurring.

This is why Tidemark treats shareability not as a feature added after the ranking logic is settled, but as a constraint on how the ranking works. The tool produces a ranked list that any team member can inspect - tracing which feedback patterns drove an item up or down - and annotate with context. Disagreement moves from “I feel like we should prioritize this” to “I think this pattern in the feedback is weighted wrong, and here is why.” That shift is the mechanism by which Tidemark turns scattered signals into a roadmap a whole team can stand behind.

Tidemark opens for early access next week. If you manage feedback for a small team and find yourself rebuilding the same summary from scratch for every planning cycle, the tool is designed for exactly that situation.

A personal year-end reckoning with a difficult year

The year broke in two places, and understanding why it broke where it did matters more to me now than cataloguing the damage.

The project I had spent fourteen months building ended not with a failure but with a success that belonged to someone else. The distinction matters because the hardest kind of ending is not the one where you were clearly wrong. It is the one where you were approximately right, early, in a direction the world eventually validated, after you had run out of time to wait. That sequence - right direction, wrong timing, borrowed runway - creates a specific grief because it cannot be resolved by deciding you were mistaken. The outcome was not the work’s verdict.

The relationship change happened alongside this, because significant losses rarely occur singly. Elena and I had been close for five years, close enough that you stop noticing how much meaning has accumulated until it starts to shift. What changed was not her opinion of me, or mine of her - it was the shape of the thing we were doing together, and that shape no longer had room for me in it. I spent months trying to understand this as a failure - mine or hers - because “something changed and no one is exactly to blame” is a harder frame to hold than fault. Fault gives you an explanation with a subject and a verb.

What I got wrong, in both cases, was confusing outcome with verdict. I read the project’s ending as a judgment on whether I should have tried. I read the relationship’s change as evidence I had done something irreparable. These are related errors sharing a mechanism: I was treating result as explanation. But result is not explanation. A project ends because the resources ran out, because the timing was wrong, because the market moved - not because the work was unworthy. A relationship changes shape because people grow differently, because what serves two people at thirty does not serve them at thirty-four - not because someone deserves to lose it.

The thing I am choosing to carry forward is not a lesson. It is more like a corrected model. The hard year taught me, because it demonstrated at cost, that endurance and outcome are separate variables. I can stay in something fully and still have it end without vindication. This is not a consolation. It is an accurate description of how things work - which matters because inaccurate descriptions lead me back to the same confusions the next time something difficult arrives.

What I am not choosing to carry forward is the pretense that the hard parts were secretly gifts. The project’s ending was a loss. The relationship’s change was a loss. These things cost something real.

Appears in diff-pairs

• diataxis-explanation vs comparison-contrast (varies style)
• diataxis-explanation vs definitional (varies style)
• diataxis-explanation vs procedural (varies style)
• diataxis-explanation vs socratic-inquiry (varies style)