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).
Re:Rules for Writing Software Tutorials
by amenghra on Thursday January 02, 2025 @04:44PM
(#42579271)
Some people embed code in a way that’s similar to a test and then have a process to run/test all the embedded code.
Re:Rules for Writing Software Tutorials
by smitty1e on Thursday January 02, 2025 @04:46PM
(#42579299)
Given that most examples are relatives small, one could leverage org-babel[1] and write the tutorial with executable code, and go straight to .PDF!
Re:Rules for Writing Software Tutorials
by KittyCatCuddler on Friday January 03, 2025 @10:14AM
(#42586322)
I've actually contributed to the Ray Tracing In one Weekend project. The process is pretty manual. The book is actually written HTML, and the code snippets are duplicated from the source (not linked in). Before release, it's a manual process to go through each book and read/build it from scratch.
In my opinion, the open source nature really is the key thing here. Most of the issues are small things (typos, confusing verbage, etc). So it get's refined as people read it.
For example, if I'm P. Shirley and I've written a book (with code) about following light rays between a virtual camera and virtual objects. I have refactored some code to be more clear. Of course, I have iterated on this code to verify it remains correct, but the related text isn't affected. I have to remember where to paste this new code. Unless the documentation had some kind of reference to the specific file, lines, and/or function to render into the text.
What's the advice for best practices here?