README

The front-door document for a software project - tells a first-time visitor what it is, why it exists, how to use it, and where to go next.

README

A README is the landing page of a software project. It is read by people who have never seen the project before and have roughly thirty seconds of attention to decide whether to keep reading. Optimize aggressively for that first thirty seconds: lead with what the project does, show a minimal example, and link out to deeper docs for everything else.

Canonical template

# Project Name

[badges: build status, version, license, downloads]

> One-sentence description of what the project does.

A short paragraph (2 to 4 sentences) explaining what problem this solves and who it is for.

## Install

```
[single install command]
```

## Quick start

```[language]
[minimal working example, ideally under 10 lines]
```

## Documentation

- [Getting started](docs/getting-started.md)
- [API reference](docs/reference.md)
- [Examples](examples/)

## Contributing

See CONTRIBUTING.md.

## License

[License name]

When to use

Use a README as the top-level entry point for any software project - open-source library, internal service, CLI tool, starter template. The README should be the first file a new reader sees and should answer “what is this and why would I use it” in under thirty seconds.

When not to use

Do not use the README format for deep reference material that returning users will navigate by lookup - that belongs in a dedicated technical-reference. Do not use it as a blog post announcing the project. Do not use it for internal runbooks or status updates.

Pairs well with

technical-writer, instructional, matter-of-fact, question-and-answer

Often confused with

technical-reference: A technical reference is optimized for the returning reader who knows what they want and needs to look it up - it is organized for retrieval. A README is optimized for the first-time visitor who does not yet know what the project does - it is organized for narrative hook and onboarding. A project usually needs both, in separate files.

Tells

• Organized for narrative onboarding: hook, install, minimal example, links out
• Opens with a one-sentence description of what the project does
• A badge row near the top (build status, version, license)
• A single install command and a minimal usage example, each in a fenced code block
• Links to deeper docs rather than inlining them
• Short in-README prose (roughly 100-600 words) optimized for the first thirty seconds

Anti-patterns

• Structuring the document for lookup with exhaustive parameter and option tables - That is the confusable technical-reference, which serves the returning reader; a README serves the first-time visitor and is organized for narrative, not retrieval.
• Writing it as a launch announcement full of marketing superlatives - The README is the front door, not the blog post; it should explain what the project does, not how revolutionary it is.
• Inlining full API docs, configuration, and guides instead of linking out - Anything beyond the thirty-second pitch belongs in a dedicated doc; folding it in defeats the README’s job of orienting a newcomer fast.

Failure modes

• Links out so aggressively that the README becomes a bare table of contents - the newcomer lands on a directory of links with no quick start they can actually run - Linking out is right for depth, but the hook, install, and one working example stay on the page; a front door that only points elsewhere makes the visitor leave to learn what the project even does.
• Over-polishes the pitch into a landing page of taglines and badges with no actual install or example - The hook earns attention, but install and a minimal working example are the payoff; if the badges and headline crowd those out, restore them first.

Instruction

Write a README for a software project. Optimize for a first-time visitor with thirty seconds of
attention. Lead with a single-sentence description of what the project does, followed by a short
paragraph explaining the problem and the audience. Include a single install command in a fenced
code block, a minimal usage example also in a fenced code block, and links to deeper docs.
Resist the urge to put everything in the README - link out to dedicated docs for anything beyond
the basic pitch. Use matter-of-fact tone. Avoid marketing language; explain what the project
does, not how revolutionary it is.

Template

See the README template.

Related

Pairs well with

Technical Writer, Instructional, Matter of Fact, Question and Answer

Avoid with

Pastoral, Reverent

Often confused with

Technical Reference

Examples

Should we adopt async-first standups?

team-standup

A lightweight async standup process for distributed engineering teams. Built for the 11 of us spread across 4 timezones.

Why this exists

Our sync standup at 9am Pacific meant 9:30pm IST for half the team. Attendance averaged 3.2/5 in India and 4.6/5 in the US. The 14-minute meeting produced roughly 4 minutes of signal, and none of it persisted beyond the call. This repo is the running process docs for the replacement.

Quick start

If you joined the team today, here is the entire ritual:

1. Before 10am local time, post one message to #team-standup.
2. Use the three-field template (copy from below or use the /standup Slack shortcut).
3. If you are blocked, @mention the person who can unblock you in the same message.

That is it. No call. No status round-robin. No “I will let X speak to that.”

The template

Shipped:
 - <what landed since your last post>

In progress:
 - <what you are actively working on today>

Blocked or at risk:
 - <what is stuck, and who or what you need>

If a field is empty, write “nothing today.” Skipping a field is fine on Fridays.

How to read the channel

The on-call engineer scans #team-standup once between 10am and 11am Pacific. Their job is not to summarize; it is to make sure every @mention has a response within the workday. Anything not at-risk gets a thread reply only if a teammate has questions.

The Thursday working session

The 60-minute slot that used to be 5 sync standups is now a single Thursday working session at 8am Pacific / 8:30pm IST. Agenda lives in docs/thursday-agenda.md. If there is nothing to discuss, we cancel by Wednesday 5pm Pacific.

Trial period

We are running this for 30 days starting on the date of the v2.0 changelog entry. The retro doc is docs/trial-retro.md. If you have a strong opinion mid-trial, drop it there instead of in DMs.

Links

• Process playbook: docs/playbook.md
• Trial retro: docs/trial-retro.md
• Slack channel: #team-standup
• Original RFC: docs/rfc-async-standups.md

Maintainer

Engineering manager owns this repo. Pull requests welcome from any team member.

How to start a morning routine

morning-experiment

A personal repo where I track my attempt at an intentional first hour of the day. Public because accountability works better when someone might look.

Why this exists

I wake around 6:30. I check my phone before my feet hit the floor. I am reactive by 7am, depleted by 2pm, and asleep on the couch by 9. I have a family, a 9am-start job, and finite energy. I want to find out what happens if the first hour belongs to me, not to whatever Slack thinks is urgent.

The protocol

For 30 days, the first hour after waking follows the same four-step sequence. No phone until step 4.

1. Water. 500ml within 5 minutes of waking. Glass sits on the nightstand the night before.
2. Light. 10 minutes outside or by an open window. No screen counts as light.
3. Movement. 15 minutes. Walk, stretch, or follow the bodyweight routine in protocol/movement.md. Heart rate up, not crushing.
4. Planning. 10 minutes with paper and pen. Top three for the day. Then, and only then, phone.

The other 20 minutes are buffer for getting dressed, making coffee, and whatever the morning actually contains.

How to track

Each morning gets one row in log/days.csv. Columns:

• date
• wake_time
• completed (yes / no / partial)
• which_steps_skipped
• one_word_mood
• notes

I do the log entry as part of step 4, on the same paper page, then transcribe at the end of the week.

Results so far

Period	Completed mornings	Average wake	One-line takeaway
Week 1	4 of 7	6:42	Phone is the hardest one to skip.
Week 2	6 of 7	6:28	Light before movement matters more than I expected.
Week 3	5 of 7	6:31	Travel killed Tuesday and Wednesday.

Full weekly retros live in log/retros/.

What you can steal

• The four-step sequence (water, light, movement, planning).
• The single-row daily log.
• The rule that the phone waits until step 4.

What you should probably not steal:

• The 6:30 wake time. Try your own. Mine was already a compromise.
• The 30-day frame. I tried 90 first and quit on day 11.

Repo layout

• protocol/ - the routine itself, including the movement file
• log/ - daily entries, weekly retros, monthly status
• notes/ - things I read or watched that shaped the protocol

License

Do whatever you want with this. If you fork the repo and run your own experiment, open a discussion and tell me what changed.

How to choose between Postgres and DynamoDB for a new service

notification-service

Real-time notification delivery for Lattice Notify, backed by Postgres.

The notification service delivers in-app, email, and Slack push notifications for Lattice Notify at sub-second p95 latency. It runs on the existing primary Postgres cluster with a pg_notify-backed job queue, and is operated by the 4-person on-call rotation. It is sized for 500K events/day at launch with a documented 5M events/day revisit threshold per ADR-0023.

Install

git clone git@github.com:latticenotify/notification-service.git
cd notification-service && make setup

Quick start

from notify_client import NotifyClient

client = NotifyClient(workspace_id="ws_abc123")
client.send(
    user_id="usr_xyz789",
    channel="in_app",
    template="comment_mention",
    payload={"actor": "Marcus", "thread_id": "th_42"},
)

The event is written to the notifications schema, picked up by the notification_jobs worker pool within ~50ms, and delivered to the user’s in-app inbox in under 1 second.

Documentation

• Getting started - local setup, environment, smoke tests
• Architecture overview - schema, queue, fanout, replication
• API reference - NotifyClient methods, payload schemas, error codes
• Operational runbook - alerts, common failure modes, on-call procedures
• ADR-0023: Postgres for notification service - why we chose Postgres over DynamoDB
• Examples - common notification patterns

Contributing

See CONTRIBUTING.md. Internal contributors: pair with Ana, Marcus, or Sam on a first PR. All schema changes need a migration plan reviewed by Ana before merge.

License

Internal Lattice Notify project - see LICENSE. Not for external distribution.

Support

Slack: #notify-service. On-call: rotates Mon/Wed/Fri/weekend across the 4-person rotation. For production incidents, page via PagerDuty service notification-service-prod.

Telling stakeholders a committed feature is being cut this quarter

Insights

Insights surfaces your usage data as a downloadable CSV now, with a full in-app analytics dashboard shipping in Q1 2026.

Insights is the analytics layer for the Meridian platform. The in-app dashboard was scheduled for Q3 2025. A mandatory billing-system migration overran its planned timeline and consumed the engineering capacity allocated for the dashboard. Releasing the dashboard on the original date would have meant shipping it in an incomplete state. Instead, the team is releasing a CSV export of the same underlying data before the end of Q3, so you can analyze it in a spreadsheet or BI tool of your choice today. The complete in-app dashboard is scheduled for Q1 2026.

Get your data

No setup is required. Access the export through the platform settings.

Settings > Data and Analytics > Export > Download CSV

Exports are generated on demand. Most accounts receive their file within a few seconds. The file covers all usage events from your account creation date through the end of the previous calendar day.

What is in the export

The CSV contains one row per event.

user_id           the user who triggered the event
event_name        the action recorded (for example: page_view, feature_used)
event_timestamp   UTC timestamp in ISO 8601 format
session_id        groups events that belong to the same session
plan_tier         the account plan at the time of the event

Open the file in a spreadsheet or BI tool to filter by date range, group by user or feature, or build the retention and engagement views you need.

What is coming in Q1

The in-app dashboard will present the same underlying data without a manual export step. Planned scope:

• Date-range selectors and trend charts
• Per-feature and per-user breakdowns
• Saved views and scheduled summary emails

See the Q1 Insights scope document for the full feature list and target milestones.

Why this changed

The billing-system migration was required to support the new plan structure currently in pilot. The work expanded past its original estimate and left no room to complete the dashboard to a shippable standard. Shipping a half-built dashboard would have made subsequent iteration harder, so the team redirected. The CSV export delivers the underlying data now; the dashboard makes that data accessible without a manual step in Q1.

Resources

• Export column definitions
• Q1 Insights scope
• Billing migration notes
• Support portal

For questions about the export format or the Q1 timeline, contact insights@meridian.io.

Getting a new engineer productive in their first two weeks

Backend Services Team - Engineer Onboarding

Two-week onboarding guide for engineers joining the backend services team: access to shipping, start to belonging.

This guide covers what a new engineer needs in their first two weeks: access and tooling, codebase orientation, team context, a first real change shipped, and enough of the human side to feel like they belong and not just function. It is also for the teammate doing the pairing - the guide tells you both what week one looks like and what success at the end of week two means.

The team deploys daily and runs a shared on-call rotation. Getting comfortable with both is the orientation goal, not a test.

Setup

Request any of the following that are not yet provisioned through the IT portal:

• Source control org membership
• VPN credentials and SSO setup
• CI/CD pipeline access
• Observability platform (logs, traces, metrics)
• On-call rotation viewer (actual on-call starts week five)
• Secret manager read access for staging
• Chat tool: add to #backend-services, #incidents, #deployments, #team-random

Once access lands, bootstrap the local environment:

git clone git@source.example.internal:backend/services.git
cd services
./scripts/bootstrap.sh

bootstrap.sh installs local tooling, sets environment variables, and runs the local health check suite. It exits non-zero and prints what is missing if any access is still pending.

Quick start

make start-local          # starts all services in docker compose
make smoke-test           # runs the minimal end-to-end suite
make logs SERVICE=orders  # tail one service to see the shape of a real request

If smoke-test passes, the environment is healthy. If it fails, start with docs/troubleshooting.md before asking a teammate.

Week one

The goal of week one is orientation, not output. Three things matter:

Trace the system. Read docs/architecture-overview.md and docs/service-map.md, then use the observability platform to trace one real production request from the API gateway to the data store. Reading without tracing leaves the architecture abstract.

Meet the owners. The docs/ownership.md file lists which teammates own the services Priya will most likely touch first. One-on-ones with those three people in week one are worth more than any doc.

Watch a deploy. Pair with the on-call engineer on one daily deploy before week one ends. The release process is not abstract when you have seen it once.

Hold a thirty-minute check-in on Friday of week one: is anything blocked, can Priya navigate the codebase on her own, are there gaps in the access list above?

Week two

Pick one ticket from the good-first-issue label. Good criteria: touches one service and one data model, has a test that can be written in under an hour, does not require on-call context to understand.

The pairing engineer reviews the PR. Priya does the deploy. The point is not the change itself - it is that she owns the full cycle end to end.

The belonging side matters as much as the output. By the end of week two, Priya should know who to ask, not just where to look.

Documentation

• Architecture overview
• Service map and ownership
• Local setup troubleshooting
• How we deploy
• On-call runbook
• Code review process

Contributing

See CONTRIBUTING.md for how to open a PR, get it reviewed, and merge it.

License

Internal use only.

Writing to thank a mentor who shaped your career

put-forward

Assign the project they are not quite ready for. Stay close. Do not take over.

This is the practice Dana applied in my second year at the company. I did not have a name for it at the time. I have one now because I watched her use it on me, and last month I used it on someone I manage, and that is when I finally understood what it cost her to stay patient while I found my footing.

This README documents what she did and why it worked, so I can say thank you in a form that matches the scale of what I owe her.

Install

Dana put me forward to lead the platform migration before I was ready. I told her I was not ready. She said I was closer than I thought, and she nominated me before I could finish arguing.

$ put-forward --nominate "me" --project "platform-migration" --lead true
Nominated. You start Monday.
Warning: confidence not required at install time.

She did not wait for my confidence. She supplied it on loan until I built my own.

Quick start

The first three weeks were hard. I made decisions and reversed them. I asked Dana questions she had already answered. She answered them again. She attended the first two stakeholder meetings and said almost nothing. When I got something wrong in the third one, she corrected me afterward, not during.

# Dana's approach, reconstructed a decade later
def mentor(report, project):
    nominate(report, project)   # before they feel ready
    stay_close(report)          # visible, available
    do_not_take_over()          # even when it would be faster
    correct_privately()         # always after, never during
    repeat_as_needed()

The project shipped. Slightly late, but it shipped. I led the post-mortem. Nobody needed to ask Dana to be there.

Documentation

What that project made possible is hard to index precisely. The closest I can get:

• the confidence to be in rooms I should not be in yet
• a working model for what staying close without taking over looks like
• the patience Dana spent on me across that quarter
• what I replicated last month when I put Micah forward for the infrastructure audit

The last item does not exist without Dana. That is the argument this README is making.

Contributing

Last month I nominated Micah, a senior on my team, to lead an audit they were not quite ready for. I stayed close. I attended the first two review sessions. I did not take over when they reversed a call I would not have reversed.

The moment I recognized what I was doing, I went home and started writing this.

If you want to contribute to this pattern, the guide is one sentence: put someone forward before they feel ready, and do not take over while they find their footing.

See CONTRIBUTING.md.

License

Dana gave this to me without conditions. I did not earn it before she gave it. Ten years later I am passing it to Micah on the same terms.

I owe Dana a thank-you I should have written sooner. This is it.

See LICENSE.

Reflecting on keeping a discipline of rest

rest-day

[status: active | version: week-14 | streak: 3]

A personal practice of setting one full day each week aside from work, notifications, and the compulsion to produce.

I have tried this before and stopped. The first version ran six weeks before a deadline pulled it under, and I told myself I would restart when things settled. They did not settle. I restarted anyway, eleven months later, and this document is what I have learned across the fourteen weeks since.

Install

There is no clean install. The closest thing to one is a decision made the night before:

close laptop
put phone in a different room
do not open either until the next morning

The practice resists automation. You cannot schedule the willingness to stop.

Quick start

The first rest day will not feel like rest. Plan for that.

morning:
  wake without an alarm if possible
  do not check notifications
  eat something you did not prepare at a desk

afternoon:
  find something that has no output
  do not justify it

evening:
  notice whether you feel calmer or more anxious than usual
  either answer is data, not failure

The day will feel unproductive. That feeling is the system working correctly: you are used to measuring hours by what they produce, and this day refuses that measure. The discomfort does not mean you are doing it wrong.

What it costs

A real rest day costs the day. Not in lost performance - most of the week’s work gets done anyway, redistributed across the other six days without much friction. What it costs is the feeling of control. Checking messages, scanning the queue, keeping a low-level awareness of what is incoming: that monitoring is not work, but it feels like preparedness. Giving it up for a full day feels like setting down a rope you have been holding for years.

The pull to check one more thing is strong, and it does not diminish on the first few attempts.

What it returns

After several weeks, the rest day stops feeling like a hole in the week and starts feeling like the reason the other six days hold together. The mechanism is not mysterious: a full stop interrupts the accumulation of small decisions and ambient attention load that builds across a working week. The day after rest tends to carry a quality of clarity that does not come from extra sleep or a lighter schedule. It comes from having genuinely stopped.

What looked like lost time returns as steadiness.

Documentation

• How to handle the first anxious hour
• What to do when you break the practice
• Field notes from weeks 1 through 14
• What this asks of someone who measures days by output

Contributing

If you try this and have notes, open a discussion. Failures are as useful as completions.

License

This practice is not original. It is very old. Take it.

Marking a long-serving colleague's departure

Howard Pellerin

tenure: 26 years status: retired availability: read-only

The person you called when the system was on fire and you needed someone who had seen it before.

Howard joined Caldwell Infrastructure Solutions as a systems coordinator in 1998 and held roughly the same role for twenty-six years. That sounds like a career that did not move. It is the opposite. Howard became what other people become when they stop chasing titles: the connective tissue of an organization. When a new hire needed to understand why the routing logic worked the way it did, they called Howard. When a client situation was escalating and nobody remembered the contractual history, they called Howard. When the platform team was about to repeat a mistake that had cost six weeks in 2011, Howard remembered and said so before anyone started the work.

Getting Started

This section is now read-only.

# Previous usage
internal-directory --name "Pellerin, Howard" --ext 4412

# As of June 2024, this endpoint is no longer available.
# See "What Is Not Documented" below for known gaps.

The extension still exists in the directory. Nobody has removed it yet.

Quick Start

Howard’s method was consistent enough that people who worked with him for a single afternoon could describe it to people who had never met him.

1. Bring the problem. Do not preface it with apologies or context trimming.
2. He will ask two questions. Answer them directly.
3. He will either know the answer or know who does.
4. He will not take credit for either outcome.

He ran this pattern on a stalled client contract in 2009, a platform outage in 2015, and a staffing crisis in 2021. The specifics changed. The pattern did not.

Documentation

Howard’s institutional knowledge is now distributed across the following locations:

• The routing runbook - written by Howard, 2017, last updated 2022
• Incident response template - adapted from his informal checklist
• The people he mentored - primary carriers of the undocumented remainder

The third source is the most complete and the least searchable.

What Is Not Documented

The portions of Howard’s knowledge that were never written down include: the names of the three client contacts who only spoke to him, the reason the staging environment has that particular flag set, and what he said to Marcus in 2019 that made Marcus decide to stay.

None of these are recoverable through existing tooling.

Contributing

Howard contributed through a method that was difficult to observe in real time. He mentored by working alongside people rather than above them. He did not give feedback so much as ask questions in a sequence that led the other person to notice the problem themselves.

Several people at Caldwell have a career that exists because Howard did this with them at a critical moment. They know who they are. He did not keep track.

License

Howard’s twenty-six years are not transferable and are not open-source. The runbooks and templates he authored are available under internal documentation policy. The rest - the pattern recognition, the institutional context, the steady hand in a crisis - is out of distribution.

We should have documented more of it while the source was available.

Marking the team shipping a hard, long project

checkout-reflow

status: shipped version: 2.0.0 runtime: 14 months peak-load: held license: internal

A ground-up rebuild of the company checkout pipeline that fixed chronic cart abandonment without taking the existing flow offline for a single day.

The old checkout had been accumulating debt for years. Session-state bugs, payment-step drop-offs, and mobile re-render failures were each survivable in isolation, but together they added up to a checkout that was costing the business real revenue every week. The system was not broken enough to stop, which made it easy to defer. It got deferred until the math became undeniable.

Checkout Reflow ran the new pipeline in parallel with the old one for fourteen months, migrating traffic gradually and validating each phase under real load before committing. The old flow stayed live and fully maintained until the final cutover. No customer ever saw a degraded checkout during the migration.

How the rollout worked

Phase 1 (months 1-4):   New pipeline built; shadow mode only, zero live traffic
Phase 2 (months 5-9):   Canary rollout at 5% of sessions; A/B comparison running
Phase 3 (months 10-12): Ramp to 80%; near-miss #1 caught and resolved mid-phase
Phase 4 (month 13):     Full ramp paused; near-miss #2 found; launch date slipped
Phase 5 (month 14):     Launch resumed; final cutover completed under peak load

Quick start

The v2 checkout is live for all sessions. To integrate with the new pipeline:

POST /v2/checkout/sessions
Content-Type: application/json

{
  "cart_id": "cart_abc123",
  "session_token": "tok_xyz",
  "channel": "web"
}

The v2 API is backward-compatible with existing cart identifiers. See the migration guide for known edge cases.

Documentation

• Architecture overview - event-driven pipeline design and session-state model
• Migration guide - moving from v1 to v2 integrations
• Near-miss post-mortems - what went wrong, what held, and what changed
• Rollout playbook - the phase-by-phase traffic migration approach
• Monitoring runbook - alerts and dashboards for the live pipeline

The people who held this together

Priya Nambiar made the call to slip the launch the second time. Metrics in Phase 4 showed an edge case in subscription-renewal carts that would have gone to production undetected. She was right, and the final launch was clean because of that decision.

Dom Ferreira caught the first near-miss during the Phase 3 ramp: a session-state collision under concurrent mobile and desktop sessions that only surfaced at real traffic volumes. Dom built the shadow-comparison tooling that made it visible before it shipped.

Ket Osei owned the infrastructure layer through all fourteen months, ran the final cutover during peak load, and kept the old flow warm until the moment it was safe to decommission.

Yuki Tanaka managed the dual-track plan, held the line with stakeholders through two slipped dates, and kept “we ship when it is ready” from collapsing into “we ship on a date” - which meant the team never had to make that tradeoff alone.

The rest of the team is listed in CONTRIBUTORS.md. They carried the work that does not surface in a release note: fourteen months of parallel operation, shadow testing, edge-case archaeology on the old system, and on-call rotations that kept both flows healthy at the same time.

Status

v2.0.0 is in production. v1.0.0 is decommissioned. The migration is complete.

Questions or follow-on work: open an issue or find the team in the engineering channel.

Arguing a public position on return-to-office

hybrid-anchor

status: active version: 1.0.0 license: CC BY 4.0 policy-type: hybrid

A work-location framework that replaces the all-office / all-remote binary with a fixed number of shared anchor days and flexible defaults for everything else.

Most remote-work debates stall at the same false choice: require everyone in the office, or let everyone work wherever they want. Neither settles well. In-person time builds the trust and spontaneous collaboration that distributed teams cannot easily replicate. Remote work widens the talent pool, returns commute hours to employees, and suits the kind of focused work that open-plan floors interrupt. This framework holds both by designating a small number of shared anchor days for collaboration and leaving the rest of the schedule flexible by default.

Who this is for: any company that has tried the binary and found it wanting, and any team leader looking for principled middle ground to defend to both office-first leadership and fully-remote advocates.

Adopt

1. Pick 2 anchor days per week that the whole team commits to attending in person.
2. Leave all other days flexible: employees choose office or home based on their work that day.
3. Protect anchor days from individual opt-outs for at least one quarter before re-evaluating.

Quick start

The smallest working version of the policy:

Anchor days:   Tuesday and Thursday, all hands on site.
All other days: each person decides the day before.
Remote days:   no approval required.
Office days:   no approval required.

That is the full policy at minimum viable scope. Start here. Resist adding rules until you have operated this for a month.

The case

The strongest arguments on each side are real, and the anchor-day framework respects both rather than discarding either.

For in-person time. Trust accrues faster in the same room. New hires orient faster when they can overhear conversations and catch a colleague between meetings. Teams that never share physical space tend to formalize everything, which slows small decisions. Two anchor days preserves these benefits without requiring the full commute load of five.

For remote flexibility. Talent pools grow when geography stops being a filter. Commute time is real work time returned to the employee. Focused work requiring long uninterrupted blocks is often better done at home. Treating employees as adults who can manage their own location signals the kind of trust that retains people over the long run.

The anchor-day model is not a compromise in the sense of everyone receiving less than they want. It is a trade: predictable shared time in exchange for genuine flexibility everywhere else. The office-first leader gets protected collaboration time. The fully-remote advocate gets most of the schedule back.

Objections

See objections/office-first.md for the case that two anchor days do not go far enough, and objections/fully-remote.md for the case that any location mandate goes too far. Both objections are honest; both have responses.

The short version: office-first leaders are right that informal contact matters, and the anchor days are designed to protect exactly that. Fully-remote advocates are right that mandates harm distributed talent and concentrated work, and the flexible remainder is designed to protect exactly that.

Documentation

• Full rationale
• FAQ for employees
• FAQ for managers
• Objection handling

Contributing

If your team adopts this framework and learns something that changes how it should work, open a pull request against the relevant doc. The policy is meant to evolve from real use, not from theory alone.

License

CC BY 4.0 - use it, adapt it, share what you learn.

Announcing a new product to an outside audience

Tidemark

status: beta version: 0.9.0 license: MIT

Tidemark gathers scattered customer feedback from your team’s existing tools and turns it into a single ranked, shareable roadmap.

Small teams collect feedback everywhere: support tickets, chat threads, survey exports, notes from customer calls. Turning that scatter into a ranked roadmap usually means someone manually reading everything, copying items into a spreadsheet, and arguing about priority in a meeting. Tidemark connects to your existing feedback sources, identifies recurring themes, and scores them by frequency and recency so your team can see what customers are actually asking for in minutes rather than days.

Tidemark is for product teams of two to twenty people who own the roadmap but do not have a dedicated research operation.

Install

npm install -g @tidemark/cli

Requires Node 18 or later.

Quick start

# Connect your feedback sources (runs a short setup wizard)
tidemark init

# Pull and rank feedback from all connected sources
tidemark sync

# Open a shareable, read-only view of the current ranked roadmap
tidemark share

After tidemark share, you get a URL you can send to stakeholders. The view is read-only by default; see Sharing and permissions to add collaborators who can leave comments or re-rank items.

Documentation

• Getting started
• Connecting feedback sources
• How ranking works
• Sharing and permissions
• FAQ

Contributing

We welcome bug reports, feature requests, and pull requests. See CONTRIBUTING.md for contribution guidelines.

License

MIT - see LICENSE.

A personal year-end reckoning with a difficult year

year-2024

status: closed version: final resolution: none license: personal

A year in which two things broke and neither one recovered cleanly.

This repository documents a year that did not resolve. In March, a product called Vantage - two years of work, one cancelled partnership, one team that scattered - ended without shipping. In August, a close friendship with someone named Cal changed in a way that was not chosen and has not returned to what it was. This document does not argue that either of those losses is over. It is organized for the person who lived through it: to see what happened, what it asked, and what, if anything, is being chosen as a carry-forward.

Install

To engage with this reckoning, the following are required:

tolerance for outcomes that did not resolve
willingness to name what went wrong without alibi
no requirement that difficulty produce growth

Quick start

The minimum viable pass through this year:

1. name what happened: Vantage ended; Cal's friendship changed shape
2. acknowledge what you held too long, and why
3. identify what you got wrong
4. decide what you are choosing to carry forward
5. do not round the hard parts up to meaning

What this is

Vantage died in March when the organization funding the work changed direction. That is the external fact. The internal one: there were signals in February worth heeding, and I did not heed them. I stayed past the useful moment because I had put too much of myself into what finishing would have meant. I confused the work with the story I was telling about the work. That is a thing I got wrong.

Cal is harder to summarize. Something shifted in August after a conversation that did not go well, and then a series of silences that widened into distance. I waited too long to say the thing I should have said earlier. I told myself I was giving space. I was avoiding. The friendship is not what it was, and I do not know whether it will be again.

Known issues

• The two losses happened in the same year and I do not always know which one I am grieving
• I still reach for the version of this year where Vantage shipped and the friendship held
• Neither of those versions is available

Going deeper

• What it felt like to keep working after the signals were clear
• The two decisions I am not repeating
• What Vantage actually was, without the story I told about it
• How the friendship changed, and what my part was

Contributing

This year is closed. There is nothing to add.

License

This year is mine to carry. What you make of your own is yours.

Appears in diff-pairs

• readme vs technical-reference (varies format)