• About the Article: Written by Ming Ying on September 19, 2024. ParadeDB has rewritten its documentation three times over a year and analyzed community support messages and user interviews to determine impactful changes.
• Why Documentation Matters: In the early days, documentation was written hastily. Flaws caused churn. Developers are cautious with startups' products and attribute documentation gaps to immaturity. First impressions matter for mission-critical products like databases.
• Deploy Documentation Like Code: Inspired by Write the Docs, ParadeDB treats docs as code. Bundling Markdown files in the monorepo and publishing to Mintlify ensures it stays in sync with the API and allows user contributions.
• Make Code Blocks Runnable: Engineers verify ParadeDB in a sandbox. Pre-populated test data and runnable code blocks streamline the process. Avoid placeholders in favor of hard-coded example values for easier copying and running.
• Test Documentation Like Code: Documented code that doesn't work hurts credibility. Committed to writing integration tests for example code blocks, reducing reports of non-working code to zero.
• Structure Documentation Like Code: Poorly organized documentation buries information. Reduced the scope of individual pages and made sections composable like code.
• Adopt Documentation Guidelines: Followed the documentation system by Divio to maintain consistency and quality.
• The Results: After the latest documentation refresh, there was a 50%+ decrease in developers asking questions already in the docs, prospective customers disengaging due to "missing features", and bug reports of unexpected behavior from API misunderstandings. The final product is at https://docs.paradedb.com/, and feedback and new contributors are welcome at https://github.com/paradedb/p... and https://github.com/paradedb/p...