<story><title>Yet Another Roguelike Tutorial</title><url>http://rogueliketutorials.com/tutorials/tcod/v2/</url></story><parent_chain><item><author>TStand90</author><text>Author here; the idea came from frustrations with the original Python roguelike tutorial on Roguebasin. Since the entire thing was written in one file, it was difficult sometimes (for me anyway) to tell what was going on.&lt;p&gt;While I&amp;#x27;m happy with the way the diff style turned out, I will say there is one big downside for me: It&amp;#x27;s a &lt;i&gt;huge&lt;/i&gt; pain to write. Not only did I do a &amp;quot;git diff&amp;quot; every time I made changes and documented it, but if you end up changing something later down the line, then I basically had to go back to the very beginning of the chapter, follow the tutorial along, and double check &lt;i&gt;everything&lt;/i&gt;. Maybe there&amp;#x27;s a more efficient way to do this, but it was a bit tedious and time consuming.&lt;p&gt;Still worth the effort in the end though, I think.</text></item><item><author>throw10920</author><text>I really, really like the &amp;quot;diff&amp;quot; style for code fragments - it makes the tutorial so much nicer to read, and I don&amp;#x27;t see any significant downsides. This should be the standard for all tutorials where you progressively modify a non-trivial body of code.</text></item></parent_chain><comment><author>munificent</author><text>My book &lt;i&gt;Crafting Interpreters&lt;/i&gt; has a similar snippet style where it shows you the surrounding context for inserted code so you can see where it goes. It doesn&amp;#x27;t show the deleted code (because that would probably get too noisy in most cases), but I could if I wanted to.&lt;p&gt;I ended up writing a whole little custom build system to automatically generate the snippets and their surrounding context based on comments in the source code [1]. It was a fairly complex program to write, but it makes it completely automatic and error-free. I can&amp;#x27;t imagine trying to maintain it all manually.&lt;p&gt;[1]: &lt;a href=&quot;http:&amp;#x2F;&amp;#x2F;journal.stuffwithstuff.com&amp;#x2F;2020&amp;#x2F;04&amp;#x2F;05&amp;#x2F;crafting-crafting-interpreters&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;http:&amp;#x2F;&amp;#x2F;journal.stuffwithstuff.com&amp;#x2F;2020&amp;#x2F;04&amp;#x2F;05&amp;#x2F;crafting-crafti...&lt;/a&gt;</text></comment>
<story><title>Yet Another Roguelike Tutorial</title><url>http://rogueliketutorials.com/tutorials/tcod/v2/</url></story><parent_chain><item><author>TStand90</author><text>Author here; the idea came from frustrations with the original Python roguelike tutorial on Roguebasin. Since the entire thing was written in one file, it was difficult sometimes (for me anyway) to tell what was going on.&lt;p&gt;While I&amp;#x27;m happy with the way the diff style turned out, I will say there is one big downside for me: It&amp;#x27;s a &lt;i&gt;huge&lt;/i&gt; pain to write. Not only did I do a &amp;quot;git diff&amp;quot; every time I made changes and documented it, but if you end up changing something later down the line, then I basically had to go back to the very beginning of the chapter, follow the tutorial along, and double check &lt;i&gt;everything&lt;/i&gt;. Maybe there&amp;#x27;s a more efficient way to do this, but it was a bit tedious and time consuming.&lt;p&gt;Still worth the effort in the end though, I think.</text></item><item><author>throw10920</author><text>I really, really like the &amp;quot;diff&amp;quot; style for code fragments - it makes the tutorial so much nicer to read, and I don&amp;#x27;t see any significant downsides. This should be the standard for all tutorials where you progressively modify a non-trivial body of code.</text></item></parent_chain><comment><author>lozenge</author><text>&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;craftinginterpreters.com&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;craftinginterpreters.com&amp;#x2F;&lt;/a&gt; is a bigger project with automated tests at each stage making sure the diffs line up. I&amp;#x27;m not sure it&amp;#x27;s open sourced though.</text></comment>