Is writing "Bad practice"-notes in tech guides bad style?
So, I'm in the process on writing a hardening guide for Windows 10. Similar to http://hardenwindows10forsecurity.com/index.html, but different in scope and style.
I wondered, if informing about "Bad/Worst Practices" would be a thing that should be avoided?
The thing is, I read several blogs in the past that told to avoid this. According to them to not give the user the knowledge that something like this exists. Honestly I feel this is quite a weak argument. If I try to explain to users why they should do something in a specific way, might it not be meaningful to tell them why not to do it in a different one?
From a didactic viewpoint I would consider the following points regarding this:
- Give only very general informations, not an actual How-To. This would mean they still have to look somewhere else - fine, if they want.
- No URLs to external guides that show this "Bad Practice" in action. Similar to the first point. If they want to use it still, I can't prevent it.
- Make it clear by a panel that this is considered as "Bad/Worst Practice" and should not be used for given reasons.
I think this sounds reasonable, but as always: Open for additional/different thoughts.
This post was sourced from https://writers.stackexchange.com/q/32441. It is licensed under CC BY-SA 3.0.
1 answer
It's very important to show users what they should not do and even more important is to explain why they should not do this.
Think of a kid: you tell it not to touch the hot surface.
... Guess what will happen five minutes later.
If you instead told the little kid that it will hurt very bad if they touch the surface because it's very hot, hotter than a candle, they will think about it twice. Depending on their experience with candles this might still lead to problems, but there will be a lot less incidents.
You want to go for the latter approach and save as many kids from hurting themselves as you can by telling them what they should not do and why they should not do it.
Your points are valid and important but the most important point is not to write:
"This will be faster, but less secure"
You want to write:
"This will save you a few minutes now, but once you have more than x users it will severely hinder your ability to perform [x] because you would have to manually change hundreds of lines - and if you miss one of them you will have a security hole that will easily grant an attacker access to your passwords."
Make it obvious why it's a bad idea. The more "You will have to do a lot more work" the better and a big "If you do this you are doomed once someone attacks you" will be better than anything else in getting people away from this action.
Don't forget to focus on the Good Practices though. It's important to mention the Bad Practices, but in general that should only be a few paragraphs or a little box at the bottom of a page with a big warning label. You are there to show them how to it right and explain why that is the right way to go, for example by mentioning the problems they will have if they don't follow your advice.
When it comes to security for example you have to know how your attackers think to be able to come up with countermeasures. If you always say that you don't need this knowledge because you are one of the good guys then the bad guys will have an easy target that knows nothing about their strategies. That would be like not telling your kids that people stealing your purse exist. Even if you don't want to encourage them to steal purses, you have to tell them that people do and how they normally do it so they can keep their purse secure.
0 comment threads
0 comment threads