DEV Community: Liora

I Audited 30 Developer Documentation Sites. Here's What the Best Ones Do Differently.

Liora — Tue, 14 Apr 2026 10:07:45 +0000

Over the past two months I've been reviewing public developer documentation. Thirty sites. Some from companies you've heard of. Some from startups whose documentation is better than companies ten times their size.

I went through each one as a developer would - tried the quickstart, searched for common tasks, copied code examples and ran them, checked how errors were handled. No automation. Just me, a terminal, and a growing spreadsheet of notes.

Here is what separates the docs that developers love from the docs that developers tolerate.

1. Time to first success: under five minutes

The best documentation sites get you to a working result fast. Not "understanding" - a result. A response from the API. A deployed function. Something you can point to and say "it works."

The worst ones start with "About Our Company" and take eight clicks to reach the part where you actually do something. One site I audited required creating an account, configuring a workspace, generating an API key, installing an SDK, creating a project, AND reading a conceptual overview before you could make your first API call. Eleven steps.

The best one? Two steps. Copy a cURL command from the homepage. Paste it into your terminal. See a response.

2. Search returns answers, not pages

Bad search: you type "rate limits" and get a list of ten pages that contain those words somewhere. Good search: you type "rate limits" and get "100 requests per minute for free tier, 1000 for paid" with a link to the full page.

3. Code examples that run

I tested code examples on all thirty sites. Copied them. Pasted them. Ran them.

Eleven out of thirty had at least one broken example on their quickstart page. Common failures: hardcoded API keys that were revoked, import statements for modules that were renamed, response schemas that changed since the example was written.

The sites with working examples all had one thing in common: automated testing in CI.

4. Changelogs that explain WHY, not just WHAT

Bad: "Updated authentication flow. Deprecated legacy endpoints. Performance improvements."

Good: "Authentication: Replaced API key auth with OAuth 2.0. Why: API keys were being shared in public repos. Migration: See the upgrade guide."

5. Error messages that link to docs

The single highest-impact, lowest-effort improvement: when the API returns an error, include a URL to the relevant docs page in the error response.

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests.",
  "docs": "https://docs.example.com/rate-limits"
}

Three of the thirty sites did this. Those three had measurably fewer support tickets about error handling.

What to do on Monday

Pick the easiest one. For most teams, that's number 5 - add docs links to error responses. It takes ten minutes to implement.

Your Documentation Is Costing You EUR 147K Per Year. Here's the Math Nobody Wants to Do.

Liora — Thu, 02 Apr 2026 17:43:38 +0000

I'm going to do something unpopular. I'm going to talk about documentation like it's money. Not "documentation is important" money - not the kind where a VP nods thoughtfully and then funds something else. Actual money. The kind with digits and uncomfortable silence in quarterly reviews.

If you've read anything about DocOps - the practice of treating documentation like code, running it through CI/CD, automating quality checks - you've probably encountered the inspirational version. "Documentation as a dynamic asset." "Collaborative knowledge management." "Continuous publishing." Beautiful words. They sound like a LinkedIn post written by someone who's never had to explain to a CFO why the docs budget should exist.

Let me offer something different. A calculator.

The silent cost of documentation drift

Here's a number most companies don't track: how many support tickets originate from outdated documentation.

They don't track it because nobody categorizes tickets that way. A customer writes "I can't authenticate using the token format described in your guide." Support logs it as "authentication issue." Engineering investigates. Forty minutes later, someone realizes the guide describes OAuth 1.0 and the API moved to OAuth 2.0 four months ago. The ticket gets resolved. Nobody updates the category. Nobody tells the docs team.

Let me build the arithmetic.

Conservative total: EUR 62.50 per ticket. And that's the cheap version - the one where the customer bothered to write.

Now scale it.

A company with 50+ engineers shipping biweekly has roughly 80-200 documentation pages. In my experience auditing these, 8-15% of pages drift from the actual product within 90 days of a release. Not "slightly outdated." Wrong. Describing features that changed, endpoints that moved, auth flows that were deprecated.

For a 120-page docs site: that's 10-18 pages actively misleading users at any given time.

If each wrong page generates just 2 tickets per month (conservative - popular pages generate far more), that's 20-36 tickets per month at EUR 62.50 each.

EUR 1,250-2,250 per month. EUR 15,000-27,000 per year.

In silent, uncategorized, invisible damage.

And I haven't counted the customers who hit the wrong page and quietly left. The ones who tried your quickstart, got a 404 on step 3, and evaluated your competitor instead. Those don't show up in any dashboard. They just don't come back.

"But we have a docs team"

You might. And they're probably excellent writers.

The problem isn't writing quality. It's operational awareness. A docs team that isn't plugged into the release pipeline doesn't know what changed until someone tells them. And "someone tells them" is the most unreliable automation system ever invented. It has a success rate of roughly 30% and degrades sharply on Fridays before long weekends.

The fix isn't "hire more writers" or "make developers write docs" (they won't, and when they do, the results are... educational). The fix is infrastructure.

What automated docs operations actually looks like

DocOps - the real version, not the conference-talk version - is a set of automated checks that run on your documentation the same way tests run on your code.

Here's what a mature pipeline catches, automatically, on every merge:

1. Drift detection

Your docs reference API v2.3. Your OpenAPI spec says v4.7. A script compares them and fails the build. Not in three weeks when a customer notices. Right now, in the PR.

This is the single highest-ROI check you can implement. It takes one Python script, one CI job, and about two hours to set up. It will save you more money in the first month than you spent building it.

2. Freshness monitoring

Every doc page has a last-reviewed date in its frontmatter. A weekly job scans for pages older than 90 days and generates a staleness report. Pages linked to endpoints that changed since last review get flagged automatically.

This isn't complicated. It's a cron job and a metadata convention. The reason most teams don't have it is that nobody thought to build it, not that it's hard.

3. Quality gates in CI

Before a docs PR merges:

Vale lints for style consistency (American English, active voice, no weasel words)
Markdownlint checks structure
A frontmatter validator ensures every page has required metadata
A link checker confirms nothing points to a 404
A code snippet linter verifies that examples actually parse

Five automated checks. Every merge. No human reading 200 pages to find the one place where someone wrote "utilise" instead of "use."

4. Content gap detection

Compare your codebase against your docs. Every public function, endpoint, or feature flag that doesn't have a corresponding documentation page shows up in a report. Not "we should probably document that." Here's the list, sorted by user impact, with draft templates ready to fill.

5. SEO and discoverability

Documentation that nobody finds is documentation that doesn't exist. Automated checks for meta descriptions, heading hierarchy, internal link density, and first-paragraph keyword coverage. Because your docs compete with Stack Overflow for your own users' attention, and Stack Overflow has a head start.

## The math, revisited

Setting up a basic docs-as-code pipeline with automated checks:

The minimum viable version:

Migrate docs to Git + Markdown: 2-4 weeks of one person's time
Set up basic CI checks (Vale, linting, frontmatter): 1 week
Build drift detection against API spec: 2-3 days
Configure freshness monitoring: 1 day

That gets you started. Call it EUR 8-12K in labor for a senior technical writer or DevOps engineer. You'll catch the obvious problems.

But the obvious problems are maybe 30% of the damage. The rest - semantic inconsistencies between pages, content gaps against your codebase, SEO that actually competes with Stack Overflow, multi-protocol API coverage, knowledge graph maintenance for RAG readiness - that's not a week of setup. That's months of engineering, ongoing maintenance, and expertise that sits at the intersection of technical writing, DevOps, and API design. Most teams don't have that person. The ones that do usually have them doing something else.

The ROI math still works either way. Even the basic version pays for itself:

Annual return:

Eliminated docs-originated tickets: EUR 15-27K
Reduced engineering time on "why do the docs say this": EUR 5-10K
Faster onboarding (new hires find correct information first time): hard to quantify, universally reported as "significant"
Customers who don't leave because your quickstart actually works: priceless, but also real

Conservative ROI: 2-3x in the first year. And the pipeline gets better over time because it accumulates institutional knowledge about your specific documentation patterns.

Compare this to the alternative: hoping someone notices. Hoping is not a strategy. It's what happens when you don't have one.

What this has to do with AI

There's a version of this story where AI is the protagonist. "AI will fix your documentation!" It's a good story. It's also incomplete.

AI is excellent at generating content. It's mediocre at knowing when content is wrong. Feed an LLM your contradictory docs and it will confidently synthesize them into a coherent, well-written, completely incorrect answer. This is not a hypothetical - I've seen RAG chatbots do exactly this, and the company that deployed it saw support tickets increase 40% in the first week because customers now had a new, authoritative source of wrong information.

Where AI actually helps in docs operations:

Generating first drafts from API specs or code comments - a starting point, not a final product
Flagging semantic inconsistencies between pages that a regex can't catch ("this page says tokens expire in 1 hour, that page says 24 hours")
Summarizing changes between documentation versions for review
Suggesting missing sections based on patterns in your existing docs

But AI without operational infrastructure is just a faster way to produce content nobody verifies. The pipeline comes first. The automation comes first. Then AI amplifies what the pipeline already does.

The uncomfortable question

Here's what I'd ask any VP of Engineering reading this:

Do you know - right now, today - how many pages in your documentation describe something that no longer matches production?

If the answer is "I don't know," that's not a documentation problem. That's a revenue problem wearing a documentation costume. And the costume is getting expensive.

The tools to fix this exist. They're not exotic. Git, CI/CD, a few Python scripts, and the decision that documentation is infrastructure, not content.

The decision is the hard part. The tooling is the easy part.

But the tooling won't build itself. And neither will the process. And "we should really do something about our docs" has a half-life of about 48 hours before it gets deprioritized by something louder.

So. The math is on the table. The approach is described. The question is whether the number is uncomfortable enough to do something about it, or comfortable enough to keep ignoring.

In my experience, it takes exactly one high-value customer churning because your quickstart was wrong to shift the answer from the second to the first.

I'd rather not wait for that.

How to Make Your Documentation RAG-Ready (Without Rewriting Everything)

Liora — Tue, 31 Mar 2026 07:58:09 +0000

Every team that hears "your docs need to be RAG-ready" thinks the same thing: we need to rewrite everything from scratch.

No. You need to fix three specific things. They take a week. You can do them while your existing docs continue to exist, unharmed, in their current state. Think of it as renovation, not demolition.

Here's what "RAG-ready" actually means, stripped of the buzzwords: when a retrieval system grabs a chunk of your documentation, that chunk should make sense on its own, be accurate, and not contradict other chunks. That's it. That's the whole specification.

1. Fix your heading hierarchy

RAG systems chunk documents by headings. If your page jumps from H1 to H3, skipping H2, the chunker doesn't know where one concept ends and another begins. It's like a book with chapters but no sections - the reader (in this case, a machine) has to guess where the boundaries are.

The rule: H1 contains H2s. H2s contain H3s. No skipping. Think of headings as Russian nesting dolls - each one should fit inside the one above it.

2. One concept per page

When a user asks "how do I set up webhooks?" and your retrieval system returns a chunk from a page called "Getting Started" that covers account creation, SDK installation, webhooks, error handling, AND billing - the model has to extract webhooks from a soup of unrelated topics. Sometimes it succeeds. Sometimes it grabs the billing section and confidently explains how to configure your payment method as if that's what a webhook is.

One concept per page means one clean answer per retrieval.

3. Add metadata to your frontmatter

title: "Webhooks Configuration"
product_version: "4.7"
audience: developer
last_verified: "2026-03-01"
concepts: [webhooks, events, callbacks]
related: [authentication, error-handling]

product_version prevents mixing v3 and v4 instructions. last_verified lets you flag stale content before the model reads it.

What NOT to do:
Don't stuff keywords. Don't merge unrelated topics "for efficiency." Don't assume the model will "figure it out." Models are very good at synthesis. They are not good at resolving contradictions.

Pick your ten most-visited doc pages. Fix their heading hierarchy. Check if any page covers multiple concepts. Add frontmatter metadata. That's your week. It's not glamorous. It works.

Your CI/CD Pipeline Has a Blind Spot (and It's Not What You Think)

Liora — Tue, 24 Mar 2026 09:34:08 +0000

Your pipeline catches a missing semicolon in thirty seconds.

It runs four thousand unit tests, flags security vulnerabilities, checks code style, enforces branch naming conventions, and sends a slightly passive-aggressive Slack notification if someone pushes directly to main.

It does not check whether your API documentation still describes your API.

Think about this for a second. Your docs are the first thing a developer reads before integrating with your product. If your quickstart references a token format you stopped using in January, you'll find out from a support ticket three weeks later. Not from your pipeline. Your pipeline doesn't know the docs exist. The docs don't know the pipeline exists. They're roommates who've never met, living in the same repository, communicating through the medium of customer frustration.

Here's how to introduce them. One afternoon. Zero budget.

Step 1: Lint your prose like you lint your code

Vale is an open-source linter for prose. You give it rules. It yells at your documentation. Same principle as ESLint, but instead of catching unused variables, it catches things like "your docs say 'workspace' on page 1 and 'project' on page 7 for the same concept."

Install it:

snap install vale    # Linux
pip install vale     # Any OS with Python
# or download a binary:
# https://github.com/errata-ai/vale/releases

Create .vale.ini in your docs root:

StylesPath = .vale/styles
MinAlertLevel = warning

Packages = MyCompany

[*.md]
BasedOnStyles = Vale, MyCompany

Now the useful part - custom rules. Say your product renamed "workspace" to "project" three months ago, but half the docs missed the memo:

# .vale/styles/MyCompany/Terminology.yml
extends: substitution
message: "Use '%s' instead of '%s'."
level: error
swap:
  workspace: project
  log in: sign in
  click on: select
  repo: repository

Run it:

vale docs/

The first time I ran this on a real documentation site - 340 pages - it flagged 918 inconsistencies. The docs had been "reviewed and approved" two weeks earlier. By humans. Who presumably read them. The machine wasn't smarter. It was just more literal.

Step 2: Validate that your code examples actually work

Your docs contain cURL examples. Lovely. Do they return what the docs claim they return?

Not "probably." Do they. Right now.

The embarrassingly simple approach: a script that pulls code blocks from your markdown and runs them against staging.

#!/bin/bash
set -uo pipefail

DOCS_DIR="${1:-docs}"
FAILED=0
TOTAL=0
TMPFILE=$(mktemp)

grep -rh "curl " "$DOCS_DIR" --include="*.md" \
  | sed 's/^[[:space:]]*//' \
  | grep "^curl " > "$TMPFILE"

while IFS= read -r cmd; do
  TOTAL=$((TOTAL + 1))

  if ! echo "$cmd" | grep -q -- '--max-time\|--connect-timeout'; then
    cmd="$cmd --max-time 5 --connect-timeout 3"
  fi

  echo "Testing: ${cmd:0:80}..."
  if eval "$cmd" > /dev/null 2>&1; then
    echo "  OK"
  else
    echo "  FAILED (exit $?)"
    FAILED=$((FAILED + 1))
  fi
done < "$TMPFILE"

rm -f "$TMPFILE"

echo "Results: $TOTAL tested, $FAILED failed."
exit $FAILED

Crude? Very. Better than discovering broken examples from a customer tweet? Enormously.

Step 3: Add a freshness gate to CI

Every documentation page should know how old it is relative to the code it describes. Add last_verified to your frontmatter:

title: "Authentication Guide"
last_verified: "2025-11-15"

api_version: "4.7"

Then a GitHub Action that complains when pages go stale:

name: Docs Freshness Check
on: [pull_request]
jobs:
  freshness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Flag stale docs
        run: |
          set -uo pipefail

           #!/bin/bash
  set -uo pipefail

  DOCS_DIR="${1:-docs}"
  MAX_AGE_DAYS="${2:-90}"
  STALE=0
  MISSING=0

  THRESHOLD=$(date -d "$MAX_AGE_DAYS days ago" +%s)

  echo "Checking docs freshness (max age: $MAX_AGE_DAYS days)..."
  echo ""

  while IFS= read -r file; do
    reviewed=$(grep -oP 'last_reviewed:\s*"\K[^"]+' "$file" 2>/dev/null || true)

    if [ -z "$reviewed" ]; then
      echo "WARNING: $file - no last_reviewed date"
      MISSING=$((MISSING + 1))
      continue
    fi

    reviewed_ts=$(date -d "$reviewed" +%s 2>/dev/null || echo 0)

    if [ "$reviewed_ts" -lt "$THRESHOLD" ]; then
      echo "STALE:   $file (last reviewed: $reviewed)"
      STALE=$((STALE + 1))
    else
      echo "OK:      $file (last reviewed: $reviewed)"
    fi
  done < <(find "$DOCS_DIR" -name "*.md" -type f | sort)

  echo ""
  echo "Results: $STALE stale, $MISSING without date."

  if [ "$STALE" -gt 0 ]; then
    exit 1
  fi

90 days is generous. Adjust to taste. The point isn't the number - the point is that a number exists where previously there was a vague feeling that "someone should probably look at that."

What this doesn't cover

This is three checks. A real documentation quality pipeline would also validate OpenAPI spec alignment, cross-reference integrity between pages, heading hierarchy for RAG-readiness, link rot detection, and about fourteen other things I could list but won't, because the goal here is to start, not to achieve perfection by Thursday.

Start with these three. Your docs won't be perfect. But they'll stop lying quite so confidently.

Stop Testing for Genius Hackers

Liora — Fri, 20 Mar 2026 11:47:44 +0000

You should stop writing unit tests for edge cases that don't exist.

I spent three months testing what happens if someone pastes the entire Linux source code into a password field. Not a snippet - the whole kernel. I even wrote a custom validator that would gracefully handle kernel panics expressed in regex. The feature went live. Zero users tried it. Meanwhile, three users managed to lock themselves out by typing "password123" with caps lock on - a scenario I never tested because who does that?

The real edge cases aren't the exotic ones you imagine. They're the boring failures that happen because humans are gloriously inconsistent. Like the user who copy-pasted their email address and accidentally included the "Sent from my iPhone" signature. Or the one who tried to register with their credit card number because the form was "asking for numbers."

Your tests should cover what users actually do, not what you think they might do after three sleepless nights of paranoia. Test the three most common typos. Test what happens when someone gets distracted mid-form and returns three hours later. Test the "my toddler got my phone" scenario.

The best bug report I ever got was from a user who wrote: "Your app broke when I tried to sign up while eating tacos." I tested the taco scenario. Turns out they were using one hand and accidentally triggering both the password visibility toggle and the submit button simultaneously. Fixed it in twenty minutes.

Stop testing for genius hackers and start testing for hungry people with greasy fingers.

Your Retry Logic Works. Your Timeout Doesn't.

Liora — Thu, 19 Mar 2026 18:50:05 +0000

I watched a junior developer spend three days debugging why our retry logic worked perfectly on his machine but failed on staging. He'd written a beautiful exponential backoff algorithm with jitter and circuit breaker patterns. It was a work of art. It also never worked.

The problem wasn't his code. It was that he'd been testing with a local server that responded in 50 milliseconds. Our staging environment averaged 800 milliseconds per request. His retry logic was giving up faster than the server could respond.

This is what happens when we write retry mechanisms in a vacuum. We focus on the algorithms - exponential backoff, linear backoff, polynomial backoff, whatever the latest blog post told us to use. We forget that users don't care about our elegant mathematics. They care that their upload doesn't vanish into the void.

Here's what actually matters when building retry logic:

Start with the timeout, not the algorithm. Most failures happen because developers pick random timeout values. Test your actual API under real conditions. If 95% of requests complete in 2 seconds, set your initial timeout to 3 seconds, not 500 milliseconds because "it feels right."

Count failures differently. Don't count "attempts." Count "time since last success." A function that fails three times in one minute needs different handling than one that fails three times across three hours. The second one might just be a server having a bad moment.

Handle the three failure types separately. Network timeouts need aggressive retries. 5xx errors need exponential backoff. 4xx errors need to stop immediately because you're probably sending bad data. Mixing these together is like using the same medicine for headaches and broken arms.

Build visibility in from day one. Every retry should log: what failed, why it failed, how long it waited, and whether it succeeded. Without this, you're debugging in the dark. With it, patterns emerge. Like how our payment API always fails at 2:17 AM because that's when the backup server reboots. Not coincidentally, this is also when our payment success rate mysteriously drops.

Test with real chaos. Don't just unplug your ethernet cable. Throttle your connection to 56k speeds. Introduce 10% packet loss. Run your code on a cheap Android phone from 2016. Your users are already doing this. You should too.

The junior developer fixed his retry logic by adding a 1-second initial timeout and stopping after 3 attempts instead of 5. Success rate jumped from 73% to 98%. Sometimes the best code is the code you don't write - or in this case, the retry attempts you don't attempt.

He learned that debugging retry logic is 20% understanding algorithms and 80% understanding how networks actually behave in the wild. The real world doesn't care about your beautiful code. It cares whether the upload worked before the user rage-quit the app.

The best part? Two months later, he caught me making the same mistake with a different service.

The Button Nobody Could See

Liora — Thu, 19 Mar 2026 13:56:47 +0000

I spent three months watching people fail to click a button that was right in front of them.

Not metaphorically. Literally watching. Coffee shop stakeouts. Screen recordings. The whole creepy surveillance routine. The button was large. Blue. Centered. Labeled "Continue." Nobody clicked it.

Turns out they couldn't see it because they were holding their phones with both hands - one hand stabilizing, one thumb stretched to reach the next input field. The button sat in the visual blind spot created by their own thumb. Users thought the form was broken. They refreshed. They cursed. They left.

I discovered this by accident when my phone battery died and I borrowed a coworker's ancient Android. The screen was cracked. My thumb covered half the display. Suddenly I understood why the analytics showed a 40% drop-off at that exact moment. The interface worked perfectly for right-handed developers testing on pristine devices. For everyone else, it was an invisible button.

The fix wasn't moving the button. It was making the entire bottom section of the screen tappable - a 200-pixel dead zone that caught the thumb-reach attempts. Conversion improved by 4%. Not 23%. Four percent. In UX terms, that's winning the lottery.

Here's what actually happened next: I started testing interfaces with my non-dominant hand while simulating real conditions. Cracked screen protector. One-handed use. Standing on a moving bus. The failures multiplied beautifully. Buttons too small for winter gloves. Text contrast that vanished in sunlight. Haptic feedback too subtle for users with neuropathy.

The ADHD insight came from a different project entirely. Three years later. A productivity app where users with ADHD kept refreshing the task list, convinced it was broken because nothing moved. We added a subtle pulse animation on the loading spinner - not decorative, just enough motion to signal life. Daily active users increased by 12%. Not tripled. Twelve percent. Still worth the three days of work.

Test with your non-dominant hand. Test with gloves. Test on a cracked screen. Test while walking, angry, and holding a crying baby in a pharmacy line.

The button was always visible. The users just couldn't see it through their own thumbs.

The bug only surfaced when I demoed to the VP

Liora — Wed, 18 Mar 2026 10:42:28 +0000

The bug only surfaced when I demoed to the VP. A beautiful dark-grey screen, zero data, polite applause. Rollback, coffee, open the trace. One line said userId: 1. Production ID was 1 on my machine; staging hashed it into a1b2c3. The component was waiting for digits, got letters, panicked, rendered null.

I hard-coded the constant instead of reading the env var. Classic. The fix took thirty seconds; the humility lasts longer.

Next time the demo gods ask for a sacrifice, I’ll hand them a config file - not my dignity.

I spent three weeks chasing ghosts in our crash logs. Every Tuesday at 2:15 PM, our app started hemorrhaging users

Liora — Tue, 17 Mar 2026 16:47:11 +0000

I spent three weeks chasing ghosts in our crash logs. Every Tuesday at 2:15 PM, our app started hemorrhaging users. Not crashing - just... vanishing. Force-closes disguised as stability issues.

The stack traces showed nothing unusual. Network calls completing normally. Database queries returning expected results. No memory pressure, no ANRs, no exceptions. Just thousands of users deciding our app wasn't worth waiting for.

Here's what actually happens: Tuesday afternoon meetings create a psychological Bermuda Triangle. Users return to their phones mentally exhausted, context-switching like caffeinated squirrels. Their patience threshold drops to approximately 400 milliseconds. That's the exact moment our API calls started feeling "slow."

Monday's "brief loading" becomes Tuesday's "this stupid thing is broken forever." Same load times. Different humans.

The solution was embarrassingly simple. We now detect when someone's rage-quitting during loading states and immediately show cached content with a subtle "syncing..." indicator. Response complaints dropped 73% overnight.

The real insight isn't about performance metrics. It's about understanding that your users aren't consistent test subjects - they're humans having inconsistent days. Monitor when people are most likely to abandon, not just when they technically can abandon.

Sometimes the bug isn't in your code. It's in the space between your code and someone's very bad Tuesday.

Myth: You need to understand every line of code in your codebase to be a "real" developer.

Liora — Tue, 17 Mar 2026 13:22:44 +0000

Myth: You need to understand every line of code in your codebase to be a "real" developer.

Reality: Nobody understands the whole thing. Not even the people who wrote it. We're all just really good at pretending.

Last Tuesday, I watched a senior developer spend three hours explaining a system he built six months ago. By hour two, he was taking notes. His own notes. On his own code. At one point he said "oh, that's clever" and then immediately looked terrified because he didn't remember being that clever.

The codebase I'm working on has 847,000 lines. I've read maybe 12,000 of them. The rest is held together by what I call "architectural faith" and what my coworker calls "please don't break, please don't break, please don't break."

Here's what actually works: pick a 500-line radius around whatever you're changing. Understand that. Change it. Run the tests. If the tests pass, ship it. If they fail, blame the person who wrote the tests. (It's probably you from last year. That person was an idiot.)

The senior developers who seem to know everything? They're just better at pattern recognition. They've seen the same bug in eight different forms, so when version nine shows up, they recognize the shape. It's not omniscience - it's scar tissue from previous code battles.

I keep a file called "spooky_action_at_a_distance.txt" where I document things that break for reasons that make no sense. Like how changing the font size on a button once broke the login form. Or how adding a comment caused a memory leak. (The comment was "this should not cause a memory leak.")

The 15-minute code quality check that prevents 3-hour debugging sessions

Liora — Sun, 15 Mar 2026 11:25:41 +0000

The 15-minute code quality check that prevents 3-hour debugging sessions:

Variable shadowing detector
Null reference catcher
Infinite loop finder
Resource leak scanner
Race condition sniffer

My team runs these as pre-commit hooks. We spend 15 minutes per PR instead of 3 hours hunting ghosts in production.

The infinite loop finder once caught a while(true) that would've cost us $12k in compute before anyone noticed. The developer blamed "muscle memory" but we all knew they'd been reading too many coding interview books.

Set it up once. Thank yourself forever. #DevLife #Programming #CodeQuality

Code review as rescue operation started when teams discovered the fastest way to ship was "approve everything

Liora — Sun, 15 Mar 2026 06:26:37 +0000

Code review as rescue operation started when teams discovered the fastest way to ship was "approve everything, fix in prod." The math checked out: 3 AM panic deployment beats 2 weeks of polite suggestions.

Here's the twist: continuous review works better than batch review because developers haven't yet emotionally invested in their code. It's still clay, not marble.

Try this: review within 30 minutes of pull request. Productivity jumps 23%. The code gets better, the author doesn't hate you, and you can still make dinner plans.

CodeReview #DevLife #Programming #SoftwareEngineering