Issue #7403 has been updated by Nick Fagerlund. Status changed from Accepted to Rejected
As your writer, I'm rejecting this suggestion. "Recommended"/"Not recommended" is lawyer-speak that only seems nicer because the phrases take up more space and are less visually distinguishable -- in other words, because it obscures the content, imposes more of a cognitive load on the reader, and makes the document more difficult to scan quickly. This isn't appropriate for a technical reference document. Examples of high-profile code style guides that use short and punchy tags like good/bad, yes/no, and do/don't: [one][1], [two][3], [three][4]. Style guides use words that imply judgment because they're fundamentally and inescapably judgmental documents. I consider good/bad, yes/no, and do/don't to be three equal options, and I'll happily change good/bad to one of the other two if you have a preference. Feel free to re-open the issue and say which one you'd like. [1]: http://source.android.com/source/code-style.html#treat-acronyms-as-words [3]: http://www.python.org/dev/peps/pep-0008/ [4]: http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#General_Naming_Rules__body ---------------------------------------- Feature #7403: style guide - change 'good' and 'bad' for examples since these imply judgement https://projects.puppetlabs.com/issues/7403 Author: Garrett Honeycutt Status: Rejected Priority: Normal Assignee: Garrett Honeycutt Category: Target version: Keywords: Branch: Affected URL: 'Good' and 'Bad' are overloaded words which imply judgement. Perhaps we could use 'Recommended' and 'Not recommended' -- You have received this notification because you have either subscribed to it, or are involved in it. To change your notification preferences, please click here: http://projects.puppetlabs.com/my/account -- You received this message because you are subscribed to the Google Groups "Puppet Bugs" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/puppet-bugs?hl=en.
