Fix the damn search box
Owner: Alex Chen
Status: Ready to build
Timeline: 4 weeks
Last updated: May 26, 2025
Our wiki search is broken. When someone searches "deploy backend," they get 47 results including a 2019 holiday party planning doc. Real examples from last week:
- Sarah spent 45 minutes finding the API rate limiting guide (it was buried in "Infrastructure > Legacy > Archive")
- Marcus gave up looking for the new hire onboarding checklist and just asked in #general again
- The deployment runbook has 3 different versions and nobody knows which one is current
Data that matters:
- 67% of #help-general questions are "where is the doc for X?"
- Average time to find a doc: 12 minutes
- People create duplicate docs because they can't find existing ones
Phase 1: Fix search basics (2 weeks)
- Replace current search with Elasticsearch
- Index all content properly (title, body, tags, recent edits)
- Show actual relevant results instead of random garbage
Phase 2: Add helpful features (2 weeks)
- Recent/popular docs widget on homepage
- "Related docs" suggestions
- Basic tagging system
That's it. No AI, no fancy graphs, no revolutionary knowledge management. Just search that works.
As a developer, I want to:
- Search "deploy" and see the actual deployment guide first
- Find docs my team created without remembering exact titles
- See when docs were last updated so I know if they're stale
As someone writing docs, I want to:
- Tag docs so people can find them
- See what people are searching for but not finding
- Know if my doc is actually being used
We'll know this worked if:
- Search success rate >80% (currently ~30%)
- #help-general wiki questions drop by half
- People stop creating duplicate "how to deploy" docs
We'll measure:
- Click-through rate on search results
- Time from search to finding the right doc
- Number of "doc not found, created new one" incidents
What we're using:
- Elasticsearch for search indexing
- Current auth system (no changes needed)
- Existing wiki database (just better indexing)
Performance requirements:
- Search results in <1 second
- Reindex new docs within 5 minutes
- Works on mobile (responsive design)
Risk: Elasticsearch is new to our team
Mitigation: Jordan has used it at previous job, will pair with backend team
Risk: Content migration breaks existing links
Mitigation: We're not moving content, just improving search indexing
Risk: People still won't find docs because docs are actually bad
Mitigation: Phase 2 includes analytics to identify which searches fail most
- DevOps: Elasticsearch cluster setup (1 week)
- Design: New search UI mockups (3 days)
- Content team: Clean up obviously outdated docs before launch
- AI-powered anything
- Changing how people write or organize docs
- New permissions or access controls
- Integration with external tools
- Mobile app
Week 1: Elasticsearch setup + data migration
Week 2: Basic search implementation
Week 3: UI improvements + tagging
Week 4: Polish + launch
Launch plan: Soft launch to engineering team first, then company-wide if no major issues.
Open questions:
- Should we archive docs that haven't been viewed in 2+ years?
- Do we need to notify doc owners when their content isn't being found?
Next steps:
- Jordan starts Elasticsearch spike Monday
- Design review with Sarah Wednesday
- Engineering kick-off Friday