The Hub Evolution: From Static Docs to Decision Dashboard

I used to dread documentation. We'd write comprehensive PRDs, discovery docs, validation plans, all beautifully formatted in Notion. Then they'd sit there, forgotten, while we built the product.

Six months later, a new team member would ask "Why did we build it this way?" and we'd scramble to find the doc. If we found it, it was outdated. The decisions had evolved, but the docs hadn't.

Documentation felt like a compliance exercise, not a strategic asset.

The problem wasn't that we documented too much. It was that documentation was static.

So we built the opposite: The Hub, a living, real-time portfolio dashboard that surfaces every idea, every doc, every validation result, and every verdict in one searchable interface.

The Hub answers three critical questions at a glance:

1. What ideas do we have? (Portfolio scores, verdicts, priority labels)
2. Where are they in the pipeline? (Discovery, Validation, Build, Scale)
3. What should we work on next? (Filters: Top Priority, Proceed, Pivot)

Real talk: it's become our most-used tool. More than Figma. More than GitHub. More than Slack.

The Problem: Why Most Docs Are Graveyards

Let me tell you about the pattern I've seen at every company I've worked with.

The Typical Death Spiral

Phase 1: Enthusiasm

Team decides "we need better docs!" Everyone agrees. Someone (usually me, let's be honest) sets up a Notion workspace or Confluence wiki. Templates get created. Guidelines get written.

Phase 2: Initial Effort

The first few projects get comprehensive documentation, discovery notes, PRDs, technical specs, meeting notes, retrospectives. It feels organized. Leadership is happy. "Finally, we're doing this right."

Phase 3: Decay

New projects start. People are busy. Docs get abbreviated:

• "TODO: Fill this in later"
• Copy-paste templates with placeholder text still in them
• Quick notes in Slack that never make it to the wiki
• "It's documented in the code comments" (spoiler: it's not)

Phase 4: Abandonment

Docs are now half-complete, inconsistent, and outdated. Searching returns nothing useful. Engineers stop checking docs before building. Product managers re-ask questions that were already documented.

The wiki becomes a graveyard.

I've watched this cycle play out at three different companies. It's not a people problem, it's a system problem.

Why Documentation Dies

After debugging this pattern for years, here's what kills docs:

No Single Source of Truth: Docs scattered across Notion, Google Docs, Slack threads, GitHub issues, Figma comments. No one knows where to look, so they just ask in Slack instead.

No Connection to Decisions: You can't see which features have docs, which don't, or which docs led to actual decisions versus speculation.

No Status Visibility: Try answering "how many ideas are in validation?" You'll spend 20 minutes manually auditing folders and still not be sure.

No Decision Support: Docs don't surface verdicts. You have to read the full discovery doc to find the Opportunity Score, read the validation plan to find the thresholds, read the results doc to see if they passed.

Terrible Search: Most wikis have search that's somehow worse than Google from 2005. Keyword searches return dozens of irrelevant results. No way to filter by doc type or project status.

The result? Tribal knowledge. When docs fail, knowledge lives in people's heads.

• "Ask Sarah about the pricing strategy"
• "Check Slack for the original requirements"
• "I think we validated that idea but I'm not sure"

Onboarding new team members takes weeks. Critical decisions get re-litigated because no one remembers the original reasoning.

I was tired of this pattern. So we built the opposite.

The Solution: The Hub as a Living Dashboard

Here's what we built instead: a portfolio dashboard that automatically discovers, indexes, and surfaces all documentation.

The Hub doesn't replace docs, it makes them findable, filterable, and actionable.

What You See When You Open the Hub

Open the Hub and you immediately see project cards laid out like this:

Each card shows everything you need to know:

• Project name (extracted from the folder or portfolio score doc)
• Portfolio score (0-40, with visual stars)
• Priority label ("Top Priority" ≥30, "High Priority" 25-29, etc.)
• Verdict badge (PROCEED = green, PIVOT = yellow, KILL = red)
• Doc counts per phase (Discovery, Validation, Build)
• Link to detail view (full list of docs)

At the top, filter buttons let you focus:

Click a filter, the list updates instantly. No loading spinners, no API calls. Just immediate focus.

What changed everything for us: the Hub shows you what matters without making you dig for it.

How It Actually Works (The Technical Bits)

Alright, let me get nerdy for a minute. Here's how the Hub works under the hood.

Step 1: Automatic Document Discovery

The Hub API scans our filesystem and finds all the docs automatically:

Step 2: Extract from Docs

For each portfolio score doc, we extract the important bits:

Step 3: Sort by Score, Return JSON

We sort everything by score (highest first) and return structured data to the frontend.

The frontend filters and renders project cards based on your selection.

Surprisingly, the whole thing runs in about 200ms, because we're just reading files, not hitting a database.

Real-World Impact: The Before and After

Let me show you what changed when we launched the Hub three months ago.

What changed most: the quality of our decisions.

Before the Hub, kill/greenlight meetings were painful. We'd debate whether we'd already validated something, or what score we'd given an idea, or whether we had the right docs.

Now? We open the Hub. Everyone sees the same data. The verdict is right there. If someone wants to revisit a decision, they can click through to see the original reasoning.

Decisions happen faster and stick better.

What We're Building Next

The current Hub is v1, functional but basic. Here's what's coming that I'm genuinely excited about:

Full-Text Search Across Everything

Right now you can only search project names. Soon: search across all docs.

Use case: "Where did we document the pricing strategy for the habit tracker?" Search "pricing habit tracker" → get `PRICING-TEST-habit-tracker.md` with highlighted snippets.

Implementation: Index all markdown files, use Fuse.js for fuzzy search. Should be ready next month.

Inline Doc Viewer

Click a doc name to view it without leaving the Hub. Modal or side panel with markdown rendering, syntax highlighting, the works.

This one's going to be huge for decision-making. Imagine reviewing a PRD or validation plan while staying in portfolio context.

AI Summarization

Auto-generate project summaries using Claude. "Summarize the validation results for this idea in 3 bullets."

I'm skeptical this will work well (AI summaries are usually too generic), but worth testing.

Analytics Dashboard

Portfolio health metrics that actually matter:

• "How many ideas did we kill this quarter?"
• "What's our average time from Discovery to Build?"
• "Which ideas have the highest scores but haven't moved to validation?"

This could help us spot patterns in what works versus what doesn't.

How to Build Your Own Hub

Alright, you're convinced this would help your team. Here's how to build one.

Fair warning: this isn't a weekend project. Budget 2-3 weeks if you're building it properly. But the ROI is worth it if you're managing 10+ ideas.

Step 1: Choose Your Documentation Structure

This is the most important decision. The Hub only works with consistent naming conventions.

Our structure:

Key principle: Consistent naming conventions. If your docs don't follow patterns, the Hub can't find them.

Step 2: Build the API to Scan Docs

We used Next.js App Router with Node.js `fs` module. You could also use Express, Fastify, whatever you're comfortable with.

The core endpoint (`GET /api/hub/projects`) needs to:

1. Scan the filesystem for portfolio score docs
2. Extract metadata (score, verdict, title) using regex
3. Count related docs in each phase
4. Sort by score (highest first)
5. Return JSON

Here's a simplified version of our API route:

Step 3: Build the Frontend

We used React + TypeScript + Tailwind. You could use Vue, Angular, plain JavaScript, whatever you prefer.

Key components:

• `<ProjectCard>`: Displays one project with score, verdict, doc counts
• `<FilterButtons>`: Toggles between All/Priority/Proceed/Pivot
• `<ProjectList>`: Maps filtered projects to cards

The filtering happens client-side (fast, no network requests):

Step 4: Polish the UI

The visual elements matter more than you think. Verdict badges, priority stars, progress indicators, they make the data scannable.

We spent a full day just on making the cards look right. Time well spent.

Step 5: Deploy and Iterate

Deploy to Vercel, Netlify, wherever. Get it in front of your team immediately, even if it's rough.

Then iterate based on usage:

• Add search if people are saying "I can't find X"
• Add doc viewer if people are opening lots of individual docs
• Add analytics if leadership wants portfolio metrics

Don't build features you think you'll need. Build features people are actually asking for.

Trade-Offs and When to Skip It

Let me be honest about the downsides.

Requires Consistent Naming: If your docs don't follow naming conventions, the Hub can't find them. This requires discipline from your team.

Filesystem-Based (Not Database): Scanning files is slower than querying a database. No support for real-time updates. Hard to add rich features like comments or version history.

Limited Search (Currently): Only project names and slugs. No full-text search yet. No filtering by doc type or content.

No Collaboration Features: Can't @mention teammates. Can't comment on projects. No notifications for doc updates.

Don't build a Hub if:

• You have < 5 ideas (a simple folder structure is fine)
• Your docs are already in a tool with good search (Notion with proper tags)
• You're a solo founder (the overhead isn't worth it)
• Your team won't maintain consistent naming conventions

But if you have 10+ ideas, multiple phases, and a need for portfolio visibility, the Hub is transformative.

The Bigger Picture

Here's what I've learned building the Hub: documentation should drive decisions, not gather dust.

The Hub works because it treats docs as structured data, not unstructured artifacts. Every doc has metadata (score, verdict, status). Every metadata field drives a UI element (badges, filters, progress bars).

This changes how you think about documentation. Instead of "let's document this for posterity," it becomes "let's structure this so the Hub can surface it."

The discipline required (consistent naming, structured metadata) pays dividends in discoverability and decision support.

What's Next for Us

We're continuing to evolve the Hub based on how we actually use it:

• Full-text search across all docs (coming next month)
• Workflow status visual progress bars (Q2)
• Inline doc viewer read without leaving Hub (Q2)
• Analytics dashboard portfolio health metrics (Q3)
• AI summarization auto-generate project summaries (experimenting)

The goal is simple: make the Hub the fastest way to answer any question about our product portfolio.

"What ideas are we working on?" → Hub.
"Which ones passed validation?" → Hub.
"What should we prioritize next?" → Hub.
"Where are the docs for that pricing experiment?" → Hub.

If you're managing multiple product ideas, I'd encourage you to build something similar. Start with automatic doc discovery, add filters for priority and verdict, and iterate from there.

Most docs systems are graveyards. Ours is a living strategy layer that drives every decision we make.

What if your documentation did the same?