>, are written in GitHub Flavored Markdown (GFM) [...] code presented in the books is contained in the Markdown files in the form of fenced code blocks.
I understand the appeal of markdown but I avoid it for writing coding tutorials because it doesn't have an easy way to annotate code with graphics like arrows and floating callouts. Here are some visual examples of code enhanced by arrows: [1][2][3]
Also, all types of text files besides programming syntax can also be explained with graphical annotations such as configuration files or log output files. E.g.[4]
Therefore, I use MS Word because it makes annotation easy. (LaTeX can also do annotation but that has its own workflow issues such as the typical programmer not knowing it which means the team can't easily update the documentation.)
IMO, annotation is important because if we performed eye-tracking and heatmap tests with people reading code tutorials, we'd see that a significant amount of time is wasted with the eyes constantly shifting back and forth between the code and the subsequent paragraphs explaining that code that's located a few inches down the page. I also think this is one reason why live coding demonstrations can sometimes be more effective than reading a book because the presenter is wiggling the mouse (or laser pointer) around the exact spot of the syntax while he's talking.
This can be somewhat mitigated with adding inline code comments in the example but often, it still doesn't point to the exact point in the line that needs to be studied. Code comments also don't easily illustrate (because it has no spatial cues) how separate lines are related to each other.
One workaround of markdown's limitation would be to rasterize the code's text into an image and then use Photoshop to annotate. However, with MS Word, that cumbersome step isn't required.
I understand the appeal of markdown but I avoid it for writing coding tutorials because it doesn't have an easy way to annotate code with graphics like arrows and floating callouts. Here are some visual examples of code enhanced by arrows: [1][2][3]
Also, all types of text files besides programming syntax can also be explained with graphical annotations such as configuration files or log output files. E.g.[4]
Therefore, I use MS Word because it makes annotation easy. (LaTeX can also do annotation but that has its own workflow issues such as the typical programmer not knowing it which means the team can't easily update the documentation.)
IMO, annotation is important because if we performed eye-tracking and heatmap tests with people reading code tutorials, we'd see that a significant amount of time is wasted with the eyes constantly shifting back and forth between the code and the subsequent paragraphs explaining that code that's located a few inches down the page. I also think this is one reason why live coding demonstrations can sometimes be more effective than reading a book because the presenter is wiggling the mouse (or laser pointer) around the exact spot of the syntax while he's talking.
This can be somewhat mitigated with adding inline code comments in the example but often, it still doesn't point to the exact point in the line that needs to be studied. Code comments also don't easily illustrate (because it has no spatial cues) how separate lines are related to each other.
One workaround of markdown's limitation would be to rasterize the code's text into an image and then use Photoshop to annotate. However, with MS Word, that cumbersome step isn't required.
[1] https://introcs.cs.princeton.edu/java/11cheatsheet/
[2] https://www.oreilly.com/library/view/head-first-python/97814...
[3] https://i.stack.imgur.com/D8JeF.png
[4] https://csharpcorner-mindcrackerinc.netdna-ssl.com/UploadFil...