-
Make the tutorial text include the code verbatim from a working repo that passes CI. No pasting necessary. Sure you still have to verify that the tutorial text aligns with the code changes, but you don't have to do anything manual to update the code in the tutorial.
As an actual example of this, here's a plugin for Remark that allows us to import specific functions from a rust source file. https://github.com/ratatui/ratatui-website/blob/main/src/plu... If the source code fails to compile, we get a CI error (in the rust checks). If the source code changes in a way where the import is no longer correct, we get a CI error (in the npm checks).
-
CodeRabbit
CodeRabbit: AI Code Reviews for Developers. Revolutionize your code reviews with AI. CodeRabbit offers PR summaries, code walkthroughs, 1-click suggestions, and AST-based analysis. Boost productivity and code quality across all major languages with each PR.
-
For that topic some nice additional stuff: https://diataxis.fr/
-
I thought that using Makefile targets was the shortest friendliest to show what a project can do. Turns out make and Makefiles can be mysterious when they fail.
Tutorials are "best-effort" and often don't dwell on the rabbit-holes they create when a poor soul runs astray of the sunny path.
Example of a good tutorial:
Python's powerline shell: https://github.com/b-ryan/powerline-shell
The README is succinct. Well put together.