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.

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.

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.

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.

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 :)

"Most software tutorials are tragically flawed.

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.

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."

https://refactoringenglish.com/chapters/rules-for-software-tutorials/

#TechnicalWriting #SoftwareDocumentation #Tutorials #SoftwareTutorials