This document is where I think through features before building them. It should stay honest, concrete, and simple: what the feature is, why it matters, and what it roughly looks like in practice.
I am not promising timelines here. This is a directional map, not a contract.
- Capture ideas first: Write the idea plainly here before touching code.
- Be specific: Describe what a user actually sees and does.
- Write trade‑offs: What I am saying “no” to by saying “yes” to this.
- Mark status honestly: Idea → Exploring → Planned → In progress → Shipped.
- Status: Idea / Exploring
- Goal: Give readers a short, standalone summary of each note that can live on its own and still be true.
- Each post can have a
tldrfield in frontmatter.- Either a single short paragraph or a small list of bullets.
- Written by me, not auto‑generated.
- On the post page:
- Show a small “TL;DR” block near the top when
tldrexists. - It should be easy to skip or skim without feeling like a second intro.
- Show a small “TL;DR” block near the top when
- Site‑wide:
- Add a “TLDRs” page that lists all TLDRs as short, standalone ideas, each linking to the full note.
- Some readers want to grasp the core idea in under 30 seconds.
- It forces clarity and synthesis in my thinking: if I can’t write a clean TLDR, the note probably isn’t sharp enough.
- A TLDRs page becomes a “idea index”: a place to browse my thinking in compressed form.
- TLDRs should:
- Be short (roughly 1–3 sentences, or 3–5 bullets max).
- Be standalone: understandable even without reading the full note.
- Be concrete: avoid vague abstractions and “guru voice.”
- Be honest: describe what the note actually delivers, not what I wish it did.
- I should not:
- Turn TLDRs into a second essay.
- Hide major caveats; if something is speculative, say so.
- Do I want TLDRs for every note, or just for the most important ones?
- Should TLDRs exist in one language only per translation group, or be translated as well?
- Status: Idea
- Goal: Let people listen to a note instead of (or while) reading it, with one simple, obvious control.
- On each post:
- A “Listen to this note” button or toggle near the top (above or near the TLDR).
- When clicked, the note is read out loud, with basic controls:
- Play / pause
- Simple progress indicator
- Ability to stop without weird behavior
- Implementation options (to decide later, but note them now):
- Browser text‑to‑speech using the Web Speech API.
- Pros: No server, no files to manage, easy to test.
- Cons: Voice quality and consistency depend on the user’s device/browser.
- Pre‑recorded audio per note (human‑voice recordings or high‑quality TTS rendered ahead of time).
- Pros: Highest quality, consistent sound.
- Cons: Time‑consuming, storage and bandwidth costs, more workflow overhead.
- Browser text‑to‑speech using the Web Speech API.
- Accessibility: some people process better by listening or can’t stare at a screen all the time.
- Convenience: readers can walk, drive, or cook while still engaging with the note.
- It forces me to write in a way that sounds human when read aloud, which is a good discipline.
- The UI should be:
- Obvious (you shouldn’t have to hunt for it).
- Calm (no auto‑play, no noisy animations).
- Respectful of user control (never starts without explicit action).
- I should favor:
- A minimal, clear player over a flashy audio UI.
- A gradual rollout: start with a small number of posts to test whether this is genuinely useful.
- Do I want to commit to recording my own voice, or stay with automated voices?
- If I use browser‑based TTS, am I okay with different voices on different devices?
- Should I support playback speed controls (1.25×, 1.5×, etc.) from day one or later?
- Status: Idea
- Goal: Let people who genuinely care about these notes opt in to hearing about new work, without turning the site into a growth‑hack machine.
- Add a clear, low‑pressure “Get updates” entry point:
- Likely on the homepage, maybe on post pages or the TLDRs page.
- Language should be honest: “Get an email when I publish something new,” not marketing fluff.
- Two main channels to consider:
- Email notifications
- A small form to collect an email address.
- Sends an email when there’s a new note (or a small digest after a period).
- Browser push notifications
- Use web push + service worker.
- Ask permission only after a clear intention signal (e.g., the user clicks a button).
- Email notifications
- Some readers don’t want to check back manually or live inside social feeds, but still want to follow the work.
- Email and/or push is a way to build a quieter, direct connection with people who genuinely care.
- It can gently support consistency: if I know someone is waiting for the next note, that’s a small accountability nudge.
- Email first, push later feels sane:
- Email is easier to reason about, friendlier to most people, and less intrusive.
- Push can be explored later if there is a clear need and a good UX pattern.
- Tone rules:
- No “growth hacks,” no manipulative copy.
- Make it easy to unsubscribe or change preferences.
- Be explicit about frequency (for example: “A few times a month at most”).
- Which email system do I want to trust (Buttondown, Substack, self‑hosted, etc.)?
- Do I only send new note alerts, or also send occasional short reflections / roundups?
- How do I handle language preferences (English vs Spanish) for notifications?
- Status: Shipped (live on site)
- Goal: Give readers an honest view of the books that shape these notes: which ones I own, which I’ve read end‑to‑end, and which I mostly use as references or have only skimmed.
- A dedicated “Library” page that:
- Lists books I actually have on my shelves / in my Kindle, not an aspirational list.
- Groups them into rough buckets:
- Read fully (cover to cover; core influences).
- In progress / partially read.
- Reference / skimmed (I dip into specific chapters or ideas).
- For each book:
- Basic metadata (title, author, category/topic).
- A short “how I use this” note: foundational, occasional reference, one‑chapter wonder, etc.
- Optional link out to the book (non‑spammy; no growth‑hack copy).
- Surface this page from:
- The About page.
- Maybe footer / nav as “Library” if it earns the space.
- Optionally from posts that mention a book (“From my library” link).
- Readers can see what they’re stepping into: which thinkers, traditions, and texts sit behind the notes.
- It makes my sources of knowledge and bias explicit, which builds more trust than pretending ideas appear from nowhere.
- It’s a simple way to recommend genuinely helpful books without turning the site into a recommendation engine.
- It gives curious readers a next step beyond the site itself: “if you liked this note, here’s what to read in the real world.”
- The page should feel like a curated shelf, not a Goodreads clone:
- No star ratings.
- No endless carousels.
- Focus on why this book matters to me, not generic blurbs.
- Buckets should stay coarse and honest (read / partial / reference) instead of fake‑precision progress tracking.
- Avoid automations that invite performative reading (no “X books this year” counters).
- Keep it manually curated so adding a book is an intentional act, not a firehose.
- Do I want to expose non‑book sources (long‑form essays, papers, lectures) on the same page or keep it strictly books?
- Should posts be able to declare related books in frontmatter so the library can show “Referenced in: …” for each title?
- Am I comfortable adding affiliate links here, or do I want this page to stay affiliate‑free for trust/clarity?
- Status: Idea
- Goal: Move the “Sources” for each note into a dedicated frontmatter field so I can surface influences and references consistently across the site, not just at the bottom of individual posts.
- Introduce a
sources(or similar) frontmatter field on posts:- Likely an array of structured entries (book, article, paper, podcast, etc.).
- Each entry can hold: title, creator (author/speaker), type, optional URL, and a short “why this matters here” note.
- In posts:
- Replace or augment the current ad‑hoc “Sources” section with data from this field.
- Keep the tone personal and honest; this is where I say how I actually used the source, not just cite it academically.
- Site‑wide:
- Add a central “Sources” view (or extend the Library page) that aggregates sources across notes:
- Filterable by type (books, essays, research, talks, etc.).
- Shows which notes each source appears in (“Referenced in: …”).
- Connect with the Library of books:
- When a source is a book that also lives in the Library, link them together instead of duplicating data.
- Add a central “Sources” view (or extend the Library page) that aggregates sources across notes:
- Makes my influences and references transparent and navigable, not buried in footers.
- Lets curious readers trace ideas back to their roots and go deeper on specific thinkers or works.
- Creates a bridge between posts and the Library page, so the site feels like one coherent knowledge graph instead of isolated essays.
- Encourages better source hygiene and humility: I’m less likely to present a borrowed idea as entirely my own when I have a canonical place to credit it.
- Keep the frontmatter schema simple enough to maintain by hand; this should not feel like filling out a citation form.
- Prioritize signal over completeness:
- Include sources that genuinely shaped the note or are helpful for readers.
- Skip automatic dumping of every casual reference.
- Avoid turning this into a gamified metric (no “most‑cited source” leaderboards).
- Design the central Sources view to feel like a map of influences, not a sterile bibliography.
- Do sources live in one place per translation group (e.g., only on the primary language), or are they duplicated/translated?
- How should I represent non‑text sources (conversations, lived experiences, unnamed influences) without forcing them into a rigid schema?
- Should I allow “site‑wide sources” (things that influence the whole project) distinct from per‑note sources, and surface those differently?
This section is intentionally rough. Quick lines only; details come later.
- Better content maps (visual overviews of themes and how notes connect).
- Gentle “related ideas” surfacing from TLDRs and tags, without feeling like a recommendation engine.
- More reader‑friendly export options (e.g., clean print/PDF for certain notes or series).