Miguel Afonso Caetano<p>Although one can find a few good advices throughout this guide, It's clear that this was written by a developer and not by a technical writer. </p><p>Besides the inability to leverage from web typography - no italics or blockquote is used to clearly distinguish the examples from the rest of the text -, the author makes too many assumptions regarding the target audience. </p><p>For instance, in the case of copy-pasteable commands, I believe that real beginners appreciate the idea of entering one command at a time and they actually might be intimated with including " && \" in a command. </p><p>Last but not least, good examples should always come first and only then, afterwards the bad examples. In this sense, the approach followed here is not very pedagogical.</p><p>In the end, I quite liked reading this text because it really made my proud of my skills, experience, and knowledge as a professional technical writer :) </p><p>"Most software tutorials are tragically flawed.</p><p>Tutorials often forget to mention some key detail, preventing readers from replicating the author’s process. Other times, the author brings in hidden assumptions that don’t match their readers’ expectations.</p><p>The good news is that it’s easier than you think to write an exceptional software tutorial. You can stand out in a sea of mediocre guides by following a few simple rules."</p><p><a href="https://refactoringenglish.com/chapters/rules-for-software-tutorials/" rel="nofollow noopener noreferrer" translate="no" target="_blank"><span class="invisible">https://</span><span class="ellipsis">refactoringenglish.com/chapter</span><span class="invisible">s/rules-for-software-tutorials/</span></a></p><p><a href="https://tldr.nettime.org/tags/TechnicalWriting" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#<span>TechnicalWriting</span></a> <a href="https://tldr.nettime.org/tags/SoftwareDocumentation" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#<span>SoftwareDocumentation</span></a> <a href="https://tldr.nettime.org/tags/Tutorials" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#<span>Tutorials</span></a> <a href="https://tldr.nettime.org/tags/SoftwareTutorials" class="mention hashtag" rel="nofollow noopener noreferrer" target="_blank">#<span>SoftwareTutorials</span></a></p>