A fresh home for all things Parseable, built by (and for) engineers.
Why we hit reset on our docs
At Parseable, clear, accurate documentation is critical, not just for users but also for us. Here's why we decided to overhaul our documentation and create the Parseable Developer Hub.
- Scaling pains with a vendor-managed portal.
Initially, we opted for a vendor-managed documentation platform. It looked great initially but quickly became cumbersome. Each new page or update involved tedious interactions with a proprietary editor, making the process slow and error-prone. Versioning, collaborative reviews, and reverting changes felt like navigating a maze far from the streamlined, developer-friendly workflow we envisioned. In short, we wanted docs-as-code, embracing transparency, speed, and collaborative editing, rather than repetitive manual data entry. - Empowering Developers to write docs.
Our team is lean, focused, and moves fast. The same engineers who build Parseable are responsible for explaining how it works. With docs-as-code, our developers directly update documentation alongside their feature work. Using GitHub PR workflows, code reviews, continuous integration checks, and instant previews via Vercel, documentation becomes part of our regular engineering process, not an afterthought. - Instant, self-hosted search with Fumadocs and Orama.
Good documentation requires great search. With our previous solution, search performance and control were suboptimal. By adopting Fumadocs, we got native, instant search powered by Orama, an in-browser search engine that’s incredibly fast and entirely self-hosted. No third-party services, API keys, or external dependencies, just millisecond results and full control over the experience.
Why Fumadocs instead of Docusaurus?
We carefully evaluated various documentation tools, and the choice narrowed down to Fumadocs and Docusaurus. Here’s what tilted our decision:
| Feature | Fumadocs | Docusaurus |
|---|---|---|
| Built-in search | Orama | Algolia DocSearch |
| Framework | Next.js | React/MDX |
| UI | Tailwind | Default |
| Deal-breaker | Local search | External search |
Given our existing expertise with Next.js (used in our Prism UI), Fumadocs provided an immediate productivity boost and a seamless integration with our tech stack.
The Benefits of our new Developer Hub
- Markdown and MDX: Write docs with ease using Markdown, sprinkle in React components when needed.
- Rapid local previews: A single command (
pnpm dev) instantly shows documentation changes. - Preview deployments: Automatically deployed PR previews on Vercel for fast, collaborative review cycles.
- Fast, in-browser search: Immediate search results without external calls, powered by Orama.
- Unified documentation repository: Docs, OpenAPI specifications, and code examples coexist in one GitHub repository, simplifying management and updates.
How it’s built
Our docs repository is straightforward, clean, and easy to contribute to:
docs/
├─ pages/ # MDX files for documentation
├─ public/ # Static assets and images
├─ lib/ # Custom plugins and extensions
└─ config files # Configuration for Next.js and Fumadocs
- Hosted on Vercel: Automated deployments with every push, instant rollback capabilities.
- CI/CD via GitHub Actions: Automated linting, link checking, search index builds, and deployment pipelines.
- In-built search: Fast and reliable search, generated at build time and served from edge functions for quick global performance.
Looking forward
- Versioned documentation: Align docs releases directly with Parseable versions.
- Interactive examples: Add playgrounds for live, hands-on exploration.
- Community-driven: Welcoming external contributions, fix typos, write guides, or improve explanations directly via GitHub.
Give it a try → https://www.parseable.com/docs
We'd love your feedback. Try searching, exploring, and interacting with the new Developer Hub. Found something or have suggestions? Open an issue or drop by our Slack, after all, docs aren’t ever truly done, just continuously improved.
