558

How I, a non-developer, read the tutorial you, a developer, wrote for me, a beginner - annie's blog (anniemueller.com)

submitted 6 days ago by SmartmanApps@programming.dev to c/programmer_humor@programming.dev

178 comments fedilink hide all child comments

you are viewing a single comment's thread
view the rest of the comments

[-] Semi_Hemi_Demigod@lemmy.world 5 points 5 days ago

I structure my tutorial docs (I write a lot of them for work) like the O’Reilly cookbook series for this reason.

The problem you’re trying to solve is at the top. Next comes a list of prerequisites for the instructions. Then clear, step-by-step instructions with no more than one command or action for each one, highlighting anything that’s different depending on environment.

Then at the bottom I’ll sometimes add a discussion of why each command does what it does, and finally a list of resources for whatever programs or systems the instructions are about.

[-] LucidNightmare@lemmy.dbzer0.com 2 points 5 days ago

Thank you for that. I'm sure the people who read it and got a grasp of what they are trying to accomplish greatly appreciate your going out of the way like that. :-]