3 ms·
I think you wrote this as as if you were transcribing yourself giving verbal instructions while standing over some junior developer's shoulder. That verbal sty
by gabesullice 2y ago
I think you wrote this as as if you were transcribing yourself giving verbal instructions while standing over some junior developer's shoulder.
That verbal style works because verbal communication is real-time and you can provide correction and feedback when something doesn't work as expected. In other words: because you're able to babysit the process and answer questions. Unfortunately, you don't have that luxury in a written medium.
I find that what works better in a written context is to have a concise list of instructions at the top with zero explanation. Below that, you can write a step-by-step explanation of the motivation and intent of each step.
This allows a reader to skip what's obvious and jump to the explanation they need to fill in a gap in their understanding.
I would also suggest you choose a specific target audience that can be expected to understand some things without explanation and who needs only a little explanation to understand a single new idea (e.g. XSS vulnerabilities, but not how to set up a project).
Another minor tip:
Make fewer value judgments and use fewer superlatives—don't write 'X is the best' or 'Y is a great'. Unless X or Y is the subject at hand, it's fine to simply say 'X is a {concise, matter-of-fact description}'.
My impression is that you have a lot in your head and that you're very excited to share that knowledge, which is awesome, but you need to share your knowledge patiently and methodically. That's a good thing though: it means you have a deep well to draw from if you enjoy writing technical articles :)