Design specification for tool to validate code snippets in documentation

Learning Team
1

I wanted to continue the conversation about how we could design and build a tool to improve code snippets throughout core ember projects.

We get some kind of code block tests in place. We burn a lot of time fixing formatting and mistakes that could be caught by a JavaScript parser. It’s more “infra” work, but in direct service of learning quality, and recaptures some time burned by the current writers & maintainers.

per @jenweber.

I heartily agree that a tool automating this would pay dividends for the learning experience. @real_ate built a POC for extracting example code blocks. I experimented with using prettier to accomplish similar formatting and validation. I think said tool should also verify documentation snippets embedded within ember source and any core project. I think we need to iteratively design a specification for it before actually building it. Doing this in a persistent, open format tailored to constructive discussion seems the best fit. Please add your ideas, expectation of what this tool should do.

  1. what would a minimum viable product look like?
  2. what other solutions exist for doing this same thing?
  3. Write it in Rust or TypeScript?
2

I was thinking of a tool like skeptic but adapted to our community’s needs: https://github.com/budziq/rust-skeptic#be-a-rust-documentation-skeptic