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
Section titled “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
Section titled “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
Section titled “Documentation”Contributing
Section titled “Contributing”See CONTRIBUTING.md.
License
Section titled “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`, `frequently-asked-questions`
### 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.
## Instruction
```textWrite a README for a software project. Optimize for a first-time visitor with thirty seconds ofattention. Lead with a single-sentence description of what the project does, followed by a shortparagraph explaining the problem and the audience. Include a single install command in a fencedcode 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 beyondthe basic pitch. Use matter-of-fact tone. Avoid marketing language; explain what the projectdoes, not how revolutionary it is.Template
Section titled “Template”See the README template.
Related
Section titled “Related”Pairs well with
Section titled “Pairs well with”Technical Writer, Instructional, Matter of Fact, Frequently Asked Questions
Avoid with
Section titled “Avoid with”Often confused with
Section titled “Often confused with”Examples
Section titled “Examples”team-standup
Section titled “team-standup”A lightweight async standup process for distributed engineering teams. Built for the 11 of us spread across 4 timezones.
Why this exists
Section titled “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
Section titled “Quick start”If you joined the team today, here is the entire ritual:
- Before 10am local time, post one message to
#team-standup. - Use the three-field template (copy from below or use the
/standupSlack shortcut). - If you are blocked,
@mentionthe 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
Section titled “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
Section titled “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
Section titled “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
Section titled “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.
- Process playbook:
docs/playbook.md - Trial retro:
docs/trial-retro.md - Slack channel:
#team-standup - Original RFC:
docs/rfc-async-standups.md
Maintainer
Section titled “Maintainer”Engineering manager owns this repo. Pull requests welcome from any team member.
morning-experiment
Section titled “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
Section titled “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
Section titled “The protocol”For 30 days, the first hour after waking follows the same four-step sequence. No phone until step 4.
- Water. 500ml within 5 minutes of waking. Glass sits on the nightstand the night before.
- Light. 10 minutes outside or by an open window. No screen counts as light.
- Movement. 15 minutes. Walk, stretch, or follow the bodyweight routine in
protocol/movement.md. Heart rate up, not crushing. - 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
Section titled “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
Section titled “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
Section titled “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
Section titled “Repo layout”protocol/- the routine itself, including the movement filelog/- daily entries, weekly retros, monthly statusnotes/- things I read or watched that shaped the protocol
License
Section titled “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.
notification-service
Section titled “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
Section titled “Install”git clone git@github.com:latticenotify/notification-service.gitcd notification-service && make setupQuick start
Section titled “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
Section titled “Documentation”- Getting started - local setup, environment, smoke tests
- Architecture overview - schema, queue, fanout, replication
- API reference -
NotifyClientmethods, 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
Section titled “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
Section titled “License”Internal Lattice Notify project - see LICENSE. Not for external distribution.
Support
Section titled “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.
Appears in diff-pairs
Section titled “Appears in diff-pairs”- readme vs technical-reference (varies format)