Date: Tue, 1 Jul 2014 07:13:08 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Eitan Adler <lists@eitanadler.com> Cc: doc@freebsd.org Subject: Re: Bad Example Formatting? Message-ID: <alpine.BSF.2.11.1407010656160.76854@wonkity.com> In-Reply-To: <CAF6rxg=j%2BsiA4cqo9gpof9d%2BBogwYr%2BZUD6jMMhdMNnEF4XVxw@mail.gmail.com> References: <CAF6rxg=j%2BsiA4cqo9gpof9d%2BBogwYr%2BZUD6jMMhdMNnEF4XVxw@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Tue, 1 Jul 2014, Eitan Adler wrote:
> Is there a way to signify good example code and bad example code?
>
> For example the latter has a light red background, and clearly says
> "don't do this" while the former has a light green background with a
> big checkmark?
I don't know if we have a way to do that short of putting it in a
<caution> or <warning>, but I have learned that it's a mistake to show
bad examples at all. Way too many people only look at the examples and
do not read the explanatory text. Seemingly all of them.
Given that, my preference would be to have the text explain what to
avoid (and why), the right way to do it, and then show the right way:
<para>Do not set permissions to <literal>777</literal>! Use only
the minimum value necessary. Only the read and execute permissions
for the file owner are needed here:</para>
<screen>&prompt.root; <userinput>chmod 600 example.sh</userinput></screen>
If an example of the wrong way is shown, explaining why it is wrong is
usually needed. But the explanation can make it even more of a
distraction.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.11.1407010656160.76854>