Skip to main content
Post Closed as "Not suitable for this site" by peterh, Jan Doggen, gnat, Erik A, Robert Columbia
edited title
Link
Pekka
  • 448.9k
  • 45
  • 207
  • 232

How(How) should I point out a bad practice in Documentation?

Source Link
Pekka
  • 448.9k
  • 45
  • 207
  • 232

How should I point out a bad practice in Documentation?

Suppose there's an example for a language feature that is bad practice to use.

I'd like to make a comment about this so future learners aren't led on the wrong path as so many have been before them. (Guess which language I'm talking about. :)

There doesn't appear to be a way to place a comment directly underneath an example.

Should I edit the example? But then everyone and their dog would start editorializing about coding styles and such so we can't have that. No?

I see a "Remarks" section further down; should I be using that?