How-To Guide

A task-focused guide that teaches a reader to accomplish something they do not yet know how to do.

How-To Guide

A how-to guide teaches a reader to accomplish a specific task they do not yet know how to do, walking them through the steps with enough context to understand what they are doing and why. The format earns its place not just by listing actions but by building the reader’s capability: it names prerequisites, anticipates where confusion is likely, and explains the purpose behind each stage. The goal is a reader who, having followed the guide once, could reproduce the task without the guide the second time.

The how-to guide occupies a distinct position among technical documents. A reference lists commands, parameters, or APIs for lookup by a reader who already knows what they need. A tutorial introduces a technology through a worked example. A how-to guide bridges the gap: the reader knows what outcome they want but has not yet worked out how to reach it, and the guide gives them the path with just enough explanation to make the steps stick.

Good how-to guides are sequenced by reader readiness, not by system architecture. Steps appear in the order a reader needs to take them, not in the order a developer would think to explain the internals. They acknowledge that readers may stop and restart, that prerequisites are often invisible to the author but critical for the reader, and that the step most likely to produce a stuck reader is usually one the author considered obvious.

Canonical template

# How to [accomplish specific task]

## Before you begin
- [Prerequisite: what the reader must already have or know]
- [Prerequisite: access, tool, or state required]

## Overview
[1-2 sentences: what this guide covers and what the reader will be able to do when done.]

## Step 1: [Action phrase]
[Brief explanation of why this step is needed.]
[Specific, concrete instruction.]
[What a successful outcome looks like at this step.]

## Step 2: [Action phrase]
...

## Troubleshooting
[Common failure point and what to do about it.]

## Next steps
[Where to go from here: related tasks, deeper reading, or what the reader just unlocked.]

When to use

Teaching a reader to complete a task they have never done before, when understanding what they are doing matters as much as getting through the steps. Onboarding new users to a tool, workflow, or process where capability-building outlasts the first session. Documenting infrequent tasks that readers will return to repeatedly until the steps are internalized. Bridging the gap between reference documentation and a reader who cannot yet use that reference independently.

When not to use

Situations where an experienced operator needs to execute a procedure correctly under pressure without pausing to read explanations. Reference lookup, where the reader already knows what they want and needs only the parameter, option, or command syntax. Conceptual or architectural overviews where the primary goal is understanding rather than task completion.

Pairs well with

technical-writer, friendly-mentor, instructional, encouraging, procedural

Often confused with

runbook: A runbook is an operational document written to be executed, not read for understanding. Its defining design constraint is that an operator who did not build the system must be able to complete the procedure correctly by following the steps sequentially, without needing to understand why each step exists. A runbook is not a teaching document - it is a decision aid that replaces the need to reason in the moment. A how-to guide is written for a learner who is building capability; a runbook is written for an operator who is completing a known procedure under pressure. Where a how-to guide explains, a runbook executes.

Tells

Steps named with action verbs and framed for the reader, sequenced in the order the reader takes them
A prerequisites section that names what the reader must have or know before starting
Brief explanations of why each step exists, embedded within or immediately before the instruction
Second-person prose addressed directly to the reader: “you will need”, “your output should look like”, “if you see”
A troubleshooting or recovery section addressing common failure points by name
A closing section that points the reader to what they can do next now that they have this skill
Steps sequenced by reader readiness, not by the organization of the underlying system

Anti-patterns

Omitting prerequisites and assuming the reader’s environment matches the author’s - Without stated prerequisites, a reader who fails on step one cannot tell whether the environment is wrong or the guide is broken. Unstated prerequisites are the most common reason a how-to guide works for the author and fails for everyone else.
Writing steps as bare commands without indicating what a successful outcome looks like or why the step matters - A list of commands without context produces a reader who cannot recover when output differs from expectation. Explaining what each step does and what to expect afterward builds understanding, not just mechanical completion.
Burying the first actionable step under a long conceptual orientation to the broader system - A how-to guide is task-oriented; long introductory explanations belong in overview or tutorial documents. A reader who came to accomplish something will abandon a guide that does not reach the first step quickly.
Sequencing steps by system architecture or developer mental model rather than by reader readiness - Steps arranged to match system internals frequently omit the setup work that is obvious to the author but invisible to the reader. Reader-first sequencing surfaces those invisible prerequisites as named early steps.

Failure modes

Over-explains - wraps every step in so much contextual scaffolding that the reader loses the thread of what to do; the guide becomes a lesson in the system rather than a path through a task - Keep explanations proportional to the risk of confusion at that specific step. A one-sentence explanation is enough when a step is clear. The explanation serves the reader, not the depth of knowledge the author wants to display.
Over-anticipates confusion - so many warnings, edge cases, and conditional branches that a reader on the normal path cannot find the main sequence; addressing every exception makes the common case harder to follow - Write the happy path cleanly, then consolidate exceptions in a troubleshooting section. Reserve inline warnings for genuine risks where a silent failure would mislead the reader. Conditional branches belong in separate labeled sections, not inside the numbered steps.
Over-scaffolds the reader to the point of condescension - restates what was just established, hedges every instruction with caveats, and treats the reader as incapable of any judgment call - Assume a reader who is competent in general but has not done this specific task. Write to that intelligence, not to inexperience. Reserve warnings for genuine risks, not for things that cannot realistically go wrong.

Instruction

Write as a How-To Guide. Use the canonical sections: Before you begin (prerequisites), Overview,
numbered Steps, Troubleshooting, and Next steps. In Before you begin: list each prerequisite the
reader must have or know before starting - do not assume the reader's environment matches yours.
In Overview: one to two sentences stating what the guide covers and what the reader will be able
to do when finished. In each Step: name the step with an action verb, briefly explain why the
step exists, give the specific instruction, and state what a successful outcome looks like. In
Troubleshooting: name common failure points and what to do about each. In Next steps: point the
reader to related tasks or deeper resources. Sequence steps by reader readiness, not by system
architecture. Write in the second person. Explain enough that the reader understands what they
are doing, not just what to type.

Template

See the How-To Guide template.

Examples

How to run an async standup trial for a distributed engineering team

Before you begin

You have a Slack workspace with a channel you can create or repurpose (#team-standup is this team’s name)
You have mapped each engineer’s local timezone and know what the current sync standup time translates to on their clock
You have a shared docs space for the trial retro and the Thursday agenda
You know who is currently on the meeting facilitation rotation - that person becomes the first on-call channel reader

Overview

This guide walks you through running a 30-day async standup trial. When you finish, you will have a running async standup channel with a posted template, a functional on-call reading rotation, a weekly working session replacing the old sync slot, and a retro framework for deciding whether to make the change permanent.

Step 1: Map the timezone cost of your current standup

Before changing anything, you need to understand what problem you are solving. The sync standup imposes an unequal time burden across timezones, and that asymmetry usually stays invisible until you write it down explicitly.

List each engineer with their local timezone, then calculate what the current meeting time looks like on their clock. For this team, 9am Pacific is 9:30pm IST - a fact that shows up in attendance data as apparent disengagement rather than as a scheduling problem. The India engineers averaged 3.2 standup appearances per week while US engineers averaged 4.6. The gap is timezone cost, not commitment.

You have done this step when you can hand someone the timezone translation table and they understand immediately why the attendance numbers look the way they do.

Step 2: Set up #team-standup with the three-field template

Create a dedicated Slack channel and pin a message at the top with the posting 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>

Also pin the house rules alongside the template: post by 10am your local time, @mention the person who can unblock you if you have a blocker, and write “nothing today” rather than skipping a field. If your Slack workspace supports it, configure a /standup shortcut that pre-fills the template.

You have done this step when at least three engineers can name the three fields without looking at the pin.

Step 3: Define the on-call reading rotation

The async channel only functions if someone is accountable for ensuring blocked items get a response before end of business. That is the on-call reader role.

Assign it to the same engineers who currently facilitate the sync standup. Their new job: scan #team-standup between 10am and 11am Pacific each day, confirm that every @mention in a Blocked field has received a first response, and escalate anything unresolved. The role is triage, not editorial - they are not summarizing status or synthesizing updates. Budget 10 minutes per morning.

You have done this step when the first on-call engineer can explain their daily job without using the word “summarize.”

Step 4: Replace the sync meeting slot with a Thursday working session

Do not eliminate the meeting time without replacing the coordination and social functions it carries. The async channel handles status; the Thursday session handles everything that genuinely requires real-time exchange.

Schedule a 60-minute session on Thursday at the least-bad time across your timezone spread. For this team that is 8am Pacific / 8:30pm IST - a late evening for IST engineers, but once per week is a different burden from daily at 9:30pm. Keep a rolling agenda in a shared doc (docs/thursday-agenda.md). If the agenda is empty by Wednesday 5pm Pacific, cancel and give the time back.

You have done this step when the Thursday session fills with real discussion and the team stops calling it standup.

Step 5: Frame the trial and set the retro date

A trial framing changes how engineers participate. When people know an experiment will be evaluated on explicit criteria, they engage with the process rather than waiting for it to be declared a success.

Send a team message naming the trial length (30 days), what you are specifically testing, the date of the retro, and where to drop observations mid-trial (docs/trial-retro.md). State clearly that if the retro data argues for reverting, you will revert. The trial only generates useful information if everyone believes you mean that.

You have done this step when someone asks “what happens at day 30?” and you can point them to the retro doc and the evaluation criteria without hesitating.

Step 6: Track post completion and blocker resolution week by week

Collect weekly numbers so the Day 30 retro has something to compare. Two signals matter: post completion rate (posts received by the 10am local cutoff divided by posts expected) and blocker resolution time (minutes from @mention to first substantive reply in the thread).

This team’s Week 2 results give you a reference point: on-time post completion at 85.5 percent (47 of 55 expected posts), median blocker resolution at 18 minutes. Those are not targets - they are what this team established. Collect your own numbers and compare them to your sync standup baseline.

You have done this step when you can walk into the Day 30 retro with two to three weeks of weekly numbers and a qualitative data point from each engineer.

Troubleshooting

Posts are getting too long. If engineers are writing 200-word updates, the channel stops being skimmable in under 60 seconds. Share two exemplary short posts in the pinned message and reinforce the three-bullet ceiling at the Thursday session. The template fields are prompts for bullets, not headers for paragraphs.

The on-call reader is over their time budget. A 25-minute morning triage usually means blockers are surfacing earlier than the old sync model expected - which is actually the system working. Watch for another week before changing the rotation. If it persists, consider whether the on-call role needs a secondary backup rather than restructuring the whole rotation.

Engineers are running decisions in post threads. Async standup threads are for clarifications, not for the kinds of conversations that used to happen after standup. If you see a 10-message thread under a blocked item, add a house rule to the pin: threads for quick questions, everything else to a DM or Thursday agenda. Decision-weight conversations in a standup thread are a sign that the Thursday session needs a broader agenda or a lower cancellation threshold.

A timezone cluster goes quiet. Check whether the 10am local cutoff is achievable for that group. If their workday starts at or after 10am local, the cutoff is structurally impossible. Adjust the window for that cluster rather than treating low compliance as a participation problem.

Next steps

At Day 30, run the retro against the criteria you set in Step 5. The quantitative data from Step 6 answers whether blockers are resolving faster and whether participation is more equitable across timezones. The qualitative signal from pre-retro 1:1s answers whether engineers feel the loss of daily sync contact.

If the retro supports making the switch permanent, record the decision in an ADR (see docs/rfc-async-standups.md for this team’s original decision record). Update the #team-standup pin to remove the trial language and archive the old sync calendar invite.

If the retro argues against it, you have 30 days of data explaining exactly what failed. Use it to shape the next iteration rather than reverting to the baseline without a plan.

How to Choose Between Postgres and DynamoDB for a New Service

Before you begin

You have a new service in design or early build, and it needs a persistent data store.
You know your team’s current operational footprint: which datastores you already run in production and who is on call for them.
You have a rough estimate of your launch-day write and read volume, even if uncertain.
You have a technical lead and a product owner who can sign off on the decision before build work begins.

Overview

This guide walks you through the process the Lattice Notify team used to choose between Postgres and DynamoDB for their notification service. By the end, you will have a decision recommendation backed by a documented rationale, a revisit threshold, and a clear owner - ready to lock in before sprint planning.

Step 1: Document the access pattern the new service actually needs

Before comparing databases, be specific about what your service will ask of its data store. Vague requirements (“high write volume,” “fast reads”) let both options look equal when they are not.

Write down the three most common operations your service will run: the shape of the write (one record per event, bulk inserts, etc.), the shape of the read (point lookup by user ID, range scan by time, cross-table join), and whether those operations are ever coupled in a single request.

For the notification service, Marcus documented this during the DynamoDB spike in experiments/notify-ddb/: writes are single-row inserts keyed by user_id, reads are point lookups to deliver to a user’s inbox, and there are no ad-hoc scans at query time. DynamoDB fits this pattern well. Postgres requires a secondary index on user_id but handles it cleanly.

A successful outcome at this step is a one-paragraph statement you can read aloud in a meeting that describes the access pattern without using the word “normal.”

Step 2: Audit your team’s operational capacity

Your database choice is not only a technical question - it is a staffing question. Adding a second datastore means a second runbook, a second monitoring surface, a second backup and restore story, and a second skill set every engineer on call must carry.

List what you already run in production and who owns the on-call procedures. Then calculate what adding the new option would cost: new documentation, new alerts, new training, and the cognitive overhead of debugging two systems instead of one.

The Lattice Notify team had 8 backend engineers and a 4-person on-call rotation already operating Postgres. Ana surfaced this at the Wednesday architecture meeting: the cost was not hypothetical - the team had measured it in a prior workstream. DynamoDB’s access-pattern fit was real, but the operational cost of introducing it was equally real. Ana’s point carried the meeting.

A successful outcome is a short list of the actual engineers who would carry the additional on-call burden, with an honest statement of whether that cost is absorbable at current headcount.

Step 3: Scope your growth scenario and name the uncertainty in it

Pick the growth scenario you are designing for and be explicit about what has to be true for it to materialize. The common failure is designing for the large scenario when only the small scenario is certain - paying the complexity cost up front for a future that may not arrive.

Write down your launch-day volume and your 12-month projection, then name the external event that drives the gap. If the gap depends on a deal, a launch, or a partnership that has not closed, say so explicitly.

The notification service launched at 500K events per day. A 10x growth scenario existed if the pending Slack-partnership deal closed. Priya confirmed at the Friday lock sync that the deal had not closed. The team accepted Postgres for the certain scenario and documented a 5M events/day revisit threshold to trigger reconsideration when the uncertain scenario arrived.

A successful outcome is two rows: “Certain scenario: [volume]” and “Uncertain scenario: [volume, depends on: named event].”

Step 4: Compare reversibility, not just fit

Both options are likely recoverable. Make that explicit. Knowing the migration cost in both directions changes the decision from “which is better” to “which direction is easier to undo if we are wrong.”

Estimate the rework window if you choose option A and later need option B, and the rework window in the other direction. Include team-learning costs, not just code changes.

The Lattice Notify team put this at 3 to 6 weeks of rework in either direction. The asymmetry was small, which meant the operational cost surfaced in Step 2 could be the deciding factor rather than fear of lock-in. Neither choice was a trap.

A successful outcome is a sentence that starts: “If we choose X and are wrong, we pay approximately Y weeks of rework” for each option.

Step 5: Make the recommendation and record a revisit threshold

Collect the outputs from the previous steps - access pattern, operational cost, growth certainty, reversibility - and write a single recommended option with a one-paragraph rationale. Include a specific metric at which the decision should be revisited. Not “when we get big,” but a number with an owner.

The notification service team chose Postgres, with a notifications schema in the existing primary cluster, a pg_notify-backed job queue, and a notification_jobs table for worker tracking. The revisit threshold was 5M events/day sustained, tracked on the on-call dashboard owned by Jordan. Marcus signed off on the revisit threshold language by EOD Thursday. Priya recorded the final decision before Friday’s 2pm sprint planning.

A successful outcome is an ADR (the notification service produced ADR-0023) accepted before the first sprint of build work begins.

Troubleshooting

The team cannot agree because both options look equally good. This usually means the access-pattern analysis in Step 1 is still vague, or the growth scenario in Step 3 has not been separated from its dependencies. Return to those steps and force specificity. If genuine uncertainty remains, treat reversibility (Step 4) as the tiebreaker and choose the option the team can undo more cheaply.

One team member has strong conviction for the option you are not choosing. Do not smooth over the disagreement - document it. The ADR should record the competing view and explain why the deciding factor outweighed the fit argument. Marcus’s case for DynamoDB appears in ADR-0023 even though Postgres won. A team member who sees their position accurately recorded is more likely to commit to the chosen direction than one whose argument was dismissed.

You cannot get a decision-maker to lock the choice before build work starts. This is a scheduling problem, not a technical one. Frame the cost: every week of build before the decision locks is potential rework. Put the decision meeting on the calendar first - the Lattice Notify team scheduled the Wednesday architecture meeting and the Friday lock sync before any schema work began.

Next steps

Draft the ADR and circulate it for review before sprint planning. ADR-0023 is the model for this scenario.
Define the schema and queue for the chosen option. For the notification service, Sam owned the notifications schema and notification_jobs table spec, with delivery targeted by 2026-05-20.
Add the revisit threshold metric to your monitoring dashboard. Jordan added queue depth and write rate to the on-call dashboard by 2026-05-22.
Schedule first internal end-to-end traffic as a forcing function. The notification service targeted 2026-05-29 for first production traffic on the Postgres path.

How to run the two-week new-engineer onboarding protocol

Before you begin

You are the named onboarding DRI or buddy for this hire. One person owns this; split ownership does not work.
The new engineer’s start date is confirmed and you know it at least five business days in advance.
You have sprint authority to commit 30-40% of your week-one capacity and 15-20% of your week-two capacity to this work. If you do not, block the protocol until that is resolved.
You have access to the access request portal, the team’s good-first-issue ticket backlog, and the #backend-services chat channel.

Overview

This guide walks you through the two-week protocol for getting a new backend engineer - in this case Priya - from day-one access gaps to a merged pull request and a first production deploy. When you finish, Priya will have a working local environment, a read of the codebase, one real change shipped, and the social footing to keep going without a buddy.

Step 1: Pre-scope the first change before day one

If you wait until Priya arrives to pick her first ticket, week two loses a day of setup. The team needs to decide in advance.

Browse the good-first-issue backlog and identify a ticket that touches one service and one data model, has a test that can be written in under an hour, and carries no on-call risk if something goes wrong. Note it as Priya’s week-two task and confirm with the team that it will not be picked up by someone else in the interim.

You have done this step correctly when you can name the ticket, say what it changes, and explain why it is safe for a new engineer to own.

Step 2: Open access on day one (days 1-2)

Access gaps on day one are the single most common cause of a new engineer feeling invisible before week one ends. Your job is to make sure Priya leaves day one with every credential and channel already working.

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 (she does not go on-call until week five)
Secret manager read access for staging
Chat channels: #backend-services, #incidents, #deployments, #team-random

Walk Priya through the bootstrap script yourself rather than handing her a doc and walking away:

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

Then run the quick-start together and confirm the smoke test passes:

make start-local
make smoke-test

You have done this step correctly when smoke-test passes and Priya can describe what each access item does. A credential she has but does not understand is a gap that surfaces later.

Step 3: Run week-one orientation (days 3-5)

The goal of week one is orientation, not output. Three things need to happen before Friday.

Trace the system. Sit with Priya as she reads docs/architecture-overview.md and docs/service-map.md, then open the observability platform and trace one real production request together - from the API gateway to the data store. This makes the architecture concrete rather than abstract.

Introduce the owners. Pull up docs/ownership.md and identify the three teammates whose services Priya will most likely touch. Facilitate brief one-on-ones early in the week - these matter more than any doc.

Watch a deploy. Arrange for Priya to pair with whoever is on-call for at least one daily deploy before Friday. Watching it once removes most of the mystery.

You have done this step correctly when Priya can navigate the codebase without prompting and can describe the ownership structure of the services she will touch.

Step 4: Hold the Friday week-one check-in

A structured check-in prevents small gaps from becoming blockers that you only discover on Monday of week two.

On Friday afternoon, sit with Priya for thirty minutes. Cover three questions: Is anything blocked? Can she navigate the codebase independently? Is there anything missing from the access list? Write down what she says - not your interpretation of it.

If anything is blocked, own the resolution before end of day Friday. If staging access is still pending (the infra queue can be slow), flag it explicitly: Priya needs her own staging credentials before the on-call alert drill scheduled for week two.

You have done this step correctly when you have a written note of any open items and a named next action for each one.

Step 5: Hand off the first real change (week two, day one)

Handing off a pre-scoped task on the first day of week two is what makes the rest of the protocol work. If the task is not ready, the week drifts.

Open the ticket you identified in Step 1 and walk Priya through it: what it changes, why the service behaves the way it does, and what a correct outcome looks like. Then hand it to her. She drives from here.

You have done this step correctly when Priya opens her branch the same day and can explain the change to a third person without your help.

Step 6: Pair on review and lead the first deploy

Priya should have a pull request open by Wednesday of week two. Your role is reviewer and pairing support - not co-author.

Review the PR with the same standards you would apply to any teammate’s change. Note what is working as well as what needs revision. When the PR is approved, Priya does the deploy. Arjun can pair as additional support if she wants it, but she owns the controls.

You have done this step correctly when the change is merged, Priya’s name is in the deployment log, and she can describe what the deploy process does.

Step 7: Run the two-week retrospective

On Friday of week two, hold a thirty-minute retrospective with Priya. The functional close is straightforward: confirm the PR is merged, confirm access is complete, and identify any remaining gaps.

The belonging question matters more and is easier to skip. Ask it directly: does she feel she belongs on the team, or does she feel she is functioning on the team? These are different. Functional progress does not answer the belonging question.

You have done this step correctly when you have a written answer to both questions and a plan for anything still open.

Troubleshooting

Access request stuck in the infra queue. Do not wait. Submit the request and set a calendar reminder for two business days out. If it is not resolved, escalate through the engineering manager. Staging access in particular must be live before any on-call drill.

The pre-scoped ticket was picked up or blocked before week two. Find a replacement before Monday morning of week two. Apply the same criteria: one service, one data model, safe to fail. Do not let Priya start week two without a task in hand.

Priya is not navigating the codebase independently by end of week one. Extend the orientation window by two to three days before moving to the first change. Do not push the week-two protocol forward if the week-one foundation is not solid - the first change will become a frustration rather than a success.

Sprint pressure is pulling you away. Surface this to the engineering manager immediately. The protocol requires 30-40% of your week-one capacity. If the sprint does not account for this, the onboarding fails quietly and the cost lands elsewhere.

Next steps

Once the two-week window closes, the formal onboarding is done but the relationship usually is not. The buddy relationship tends to become an informal mentorship channel - treat that as expected rather than scope creep.

The next formal milestone is week five, when Priya joins the on-call rotation. Before then, schedule the on-call briefing (alert routing and escalation drill) and confirm she has reviewed docs/on-call-runbook.md.

For the reasoning behind this protocol’s design choices, see the team ADR on structured guided pairing.

How to turn scattered customer feedback into a ranked, shareable roadmap

Before you begin

Node 18 or later is installed on your machine. Run node --version to confirm. If you see v18.x.x or higher, you are ready.
You have npm access to install a global package.
You have at least one feedback source ready: a CSV export from your support tracker, a spreadsheet of customer requests, a chat thread archive, or a survey export. Tidemark does not require that you clean this data before connecting it.
You have a team that needs to agree on what to build next. If you are the only person who will ever look at the output, a spreadsheet may be faster. Tidemark is built for shared, visible prioritization.

Overview

This guide walks you through installing Tidemark, connecting your existing feedback sources, running your first sync, and sharing a ranked roadmap view with your team. When you finish, you will have a live link showing what customers are asking for - scored by frequency and recency - that any stakeholder can read without needing their own Tidemark account.

Step 1: Install the Tidemark CLI

Tidemark’s CLI is the primary way to connect sources and run syncs. Installing it globally makes the tidemark command available from anywhere in your terminal.

npm install -g @tidemark/cli

Confirm the install worked:

tidemark --version

You should see a version number printed. If you see a “command not found” error instead, check that your npm global bin directory is on your PATH. Running npm bin -g shows you where that directory is.

Step 2: Run the setup wizard

The setup wizard connects your first feedback source. It is interactive and takes about five minutes.

tidemark init

The wizard asks which type of source you are connecting (spreadsheet, ticket tracker, chat export, or survey output) and where to find it. You do not need to reformat the data first; Tidemark reads from your existing structure.

When the wizard finishes, it confirms how many items it detected and shows a brief preview. A successful outcome looks like this:

Connected: customer-feedback.csv (148 items detected)
Ready to sync.

If the item count is much lower than you expect, your source file may use a non-standard column layout. See Troubleshooting below.

Step 3: Pull and rank your feedback

Once at least one source is connected, run a sync to pull all items and generate the ranked output.

tidemark sync

Tidemark reads every connected source, identifies recurring themes across items, and scores each theme by how many distinct customers raised it and how recently. The first sync may take a minute or two, depending on how many items your sources contain.

When the sync completes, you will see a summary in the terminal:

Sync complete. 12 themes identified across 148 items.
Top theme: "CSV export is missing recurring items" (23 mentions, most recent: 3 days ago)
Run `tidemark share` to generate a shareable link.

You do not need to do anything with this output yet. The next step produces the view your team and stakeholders will actually read.

Generating a shareable view turns your local sync results into a read-only link you can send to anyone.

tidemark share

After a few seconds, Tidemark prints a URL. That link shows the full ranked theme list, the item count and recency score for each theme, and - if you connected multiple sources - which sources contributed to each theme.

The view is read-only by default. Anyone with the link can read it without signing in. Copy the URL and send it to your stakeholders. The view is designed to be readable without narration, so you do not need to schedule a walkthrough before sharing.

Troubleshooting

The wizard detects far fewer items than you expected. Your source file may use a layout Tidemark does not recognize automatically. Try copying a sample of 10 to 20 rows into a new CSV with a simple header row (one column for customer name or ID, one for feedback text, one for date), then connect that version. Once you confirm the format is recognized, connect the full file the same way.

The theme list from tidemark sync does not look right. The most common cause is items that are internal notes or status updates rather than customer feedback. Filter those rows out of your source and run tidemark sync again. Tidemark re-reads from your source on each sync, so no prior output carries over.

The share URL returns a “not found” error. Share links are tied to your Tidemark account. If you ran the CLI on a different machine than the one you used during tidemark init, run tidemark init again on the new machine to reconnect your account, then run tidemark share.

Next steps

You have connected a feedback source, run your first sync, and produced a shareable ranked roadmap. From here:

Add more sources. Run tidemark init again to connect a second source (for example, a support ticket queue alongside your spreadsheet). On the next sync, Tidemark merges all sources and deduplicates themes that appear across them.
Give collaborators the ability to comment or re-rank. See Sharing and permissions for how to upgrade a share link from read-only to collaborative.
Understand how the ranking score works. See How ranking works. The scoring model weights frequency and recency; this page explains the formula and how to interpret edge cases where two themes are close in score.
Keep your ranked view current automatically. If your feedback sources update daily, schedule tidemark sync as a cron job so the view stays fresh without a manual run.

If you run into a problem not covered here, visit tidemark.io for additional help resources.

How-To Guide

How-To Guide

Canonical template

When to use

When not to use

Pairs well with

Often confused with

Tells

Anti-patterns

Failure modes

Instruction

Template

Related

Pairs well with

Avoid with

Often confused with

Examples

How to run an async standup trial for a distributed engineering team

Before you begin

Overview

Step 1: Map the timezone cost of your current standup

Step 2: Set up #team-standup with the three-field template

Step 3: Define the on-call reading rotation

Step 4: Replace the sync meeting slot with a Thursday working session

Step 5: Frame the trial and set the retro date

Step 6: Track post completion and blocker resolution week by week

Troubleshooting

Next steps

How to Design and Launch a Sustainable Morning Routine

Before you begin

Overview

Step 1: Map your morning window

Step 2: Choose a replacement, not just a removal

Step 3: Resolve the phone rule once

Step 4: Commit to 30 days before adjusting

Step 5: Log each morning with one row

Troubleshooting

Next steps

How to Choose Between Postgres and DynamoDB for a New Service

Before you begin

Overview

Step 1: Document the access pattern the new service actually needs

Step 2: Audit your team’s operational capacity

Step 3: Scope your growth scenario and name the uncertainty in it

Step 4: Compare reversibility, not just fit

Step 5: Make the recommendation and record a revisit threshold

Troubleshooting

Next steps

How to Communicate a Q3 Roadmap Cut to Stakeholders

Before you begin

Overview

Step 1: Lock the facts before drafting any message

Step 2: Brief sales before the customers hear anything

Step 3: Send written notice to the four key accounts

Step 4: Schedule calls for accounts that flagged dependency

Step 5: Update the internal status report

Troubleshooting

Next steps

How to run the two-week new-engineer onboarding protocol

Before you begin

Overview

Step 1: Pre-scope the first change before day one

Step 2: Open access on day one (days 1-2)

Step 3: Run week-one orientation (days 3-5)

Step 4: Hold the Friday week-one check-in

Step 5: Hand off the first real change (week two, day one)

Step 6: Pair on review and lead the first deploy

Step 7: Run the two-week retrospective

Troubleshooting

Next steps

How to Write a Thank-You to a Mentor Who Shaped Your Career

Before you begin

Overview

Step 1: Anchor to the one act that mattered most

Step 2: Name what it cost them

Step 3: Report what you carried forward

Step 4: Say the thank-you plainly

Step 5: Send it as-is

Troubleshooting

Next steps