Today while reading the Rust Documentation, I encountered a fantastic UX touch. The authors provide this image with each code block that intentionally doesn’t compile:
Docs have to show code that’s broken; it’s how you learn. But broken code can also confuse inexperienced programmers. I’ve seen broken code from a tutorial pasted into Stack Overflow with a plea for help, when the solution is in the next paragraph of the tutorial.
Even if the tutorial is correct, readers are getting lost. Why not say: “This is broken, but don’t worry, we’re gonna fix it!” That’s what Rust has done, and it’s thoughtful.