8 ms·
I stand by my opinion that any kind of documentation or tutorial should pass a validation step where the author does copy/paste of all their commands into a cle
by j1elo 5y ago
I stand by my opinion that any kind of documentation or tutorial should pass a validation step where the author does copy/paste of all their commands into a clean Docker container or VM image. If any error happens, your work is not done yet.
If you need to instruct users to install a compiler or an extra tool, so be it. It just must work as-is on a clean system (for which using Docker is easiest for me, but a clean VM or any other alternative is fine too).
- gmac 5y agoPreferably the author doesn't copy and paste: preferably there's a documentation build step where everything gets run, relevant outputs get inserted into the docs, and any errors get caught. This is how my docs for Zapatos[1] work, for instance. :) [1] https://jawj.github.io/zapatos/ https://jawj.github.io/zapatos/
- j1elo 5y agoIt is probably too much to ask everyone follow the same approach, so I'll be happy if people just test their own commands by hand. But your doc build step that validates code and catches errors? That's the ideal setup, for sure. Great job!
- chromatin 5y ago> I stand by my opinion that any kind of documentation or tutorial should pass a validation step where the author does copy/paste of all their commands into a clean Docker container or VM image. If any error happens, your work is not done yet. Very much this. We often write scientific software with (command-line) instructions for nontechnical or sort-of-technical users and have learned from experience to not assume anything about the user's environment, or background knowledge, and to try to replicate our documentation's instructions line-by-line!