I’ve been thinking a lot about data-driven documentation recently so I was pretty excited to see this post. However, I don’t see much actual data-driven methodology here? Don’t get me wrong; these are all solid practices. The content just doesn’t seem to match up much with the title.
Yes, saw that. Was hoping for more. Analyzing bug reports, chat room discussions, and sales pipeline dropoff are standard practices for improving docs. And backing your code samples with real runnable/testable code is a great way to increase confidence that the code samples work. You don’t necessarily need to be data-driven to adopt these approaches though. The best docs teams I know just ruthlessly fix the docs whenever they learn that customer confusion was caused by sub-par docs, regardless of whether just one customer experienced it or many. If the author is arguing that some docs work had higher impact than other docs work, I would love to see those data points.
This post is still a great overview of tried-and-true approaches for improving docs quality.
One data-driven docs approach I love for instance: crawl every single issue and scrape docs URLs from those issues in order to find docs hot spots (i.e. docs that are frequently mentioned in issues) and then use those numbers to decide what docs to focus on improving.
The usual approach is to set up a fully buildable/testable/runnable app and then pull snippets into your code. E.g. in Sphinx you can use literalinclude to pull in lines 5-10 or everything between // search_example_start and // search_example_end.
They have some other kind of system that injects the code samples into the correct locations within docs
They work in the opposite direction, extracting code samples from docs and setting up scaffolding around the snippet so that it can be built/tested/run
I’ve been thinking a lot about data-driven documentation recently so I was pretty excited to see this post. However, I don’t see much actual data-driven methodology here? Don’t get me wrong; these are all solid practices. The content just doesn’t seem to match up much with the title.
It says,
Yes, saw that. Was hoping for more. Analyzing bug reports, chat room discussions, and sales pipeline dropoff are standard practices for improving docs. And backing your code samples with real runnable/testable code is a great way to increase confidence that the code samples work. You don’t necessarily need to be data-driven to adopt these approaches though. The best docs teams I know just ruthlessly fix the docs whenever they learn that customer confusion was caused by sub-par docs, regardless of whether just one customer experienced it or many. If the author is arguing that some docs work had higher impact than other docs work, I would love to see those data points.
This post is still a great overview of tried-and-true approaches for improving docs quality.
One data-driven docs approach I love for instance: crawl every single issue and scrape docs URLs from those issues in order to find docs hot spots (i.e. docs that are frequently mentioned in issues) and then use those numbers to decide what docs to focus on improving.
I wonder what approach they took to integration-test the code blocks. Scraping HTML files, interpreting etc.
The usual approach is to set up a fully buildable/testable/runnable app and then pull snippets into your code. E.g. in Sphinx you can use literalinclude to pull in lines 5-10 or everything between
// search_example_startand// search_example_end.I don’t see any indication in their docs that they’re using that approach: https://github.com/paradedb/paradedb/blob/dev/docs/api-reference/introduction.mdx?plain=1
So either:
(Or I’m just looking at the wrong branch)
Their test-docs workflow seems to only check for broken links, presumably after lint-markdown
Is something like C4 model fit well here? With Structurizr or PlantUML it becomes code as well.