Suche
Beiträge, die mit tutorials getaggt sind
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
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
Rules for Writing Software Tutorials
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.refactoringenglish.com
#Development #Guidelines
Rules for writing software tutorials · Crafting a great tutorial is easier than you think https://ilo.im/161nru
_____
#Software #Tutorials #Terminology #CodeSnippets #Content #Blog #WebDev #Frontend #Backend
Rules for writing software tutorials · Crafting a great tutorial is easier than you think https://ilo.im/161nru
_____
#Software #Tutorials #Terminology #CodeSnippets #Content #Blog #WebDev #Frontend #Backend
Rules for Writing Software Tutorials
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.ilo.im
I invite #dataScientists and #computationalBiologists to contribute to Data All The Way! (https://dataalltheway.com). Share #tutorials, concepts, or projects (with code/Kaggle notebooks) under your name. I’ll help with editing and formatting. Contact me here or via the website to get started!
#DataScience #Bioinformatics #computationalbiology #blog #blogpost
#DataScience #Bioinformatics #computationalbiology #blog #blogpost
Data All The Way
Data All The Way: A tutorial website with concepts, methods, and example code on various data science, statistics, and machine learning topics.dataalltheway.com