Skip to main content
added 12 characters in body
Source Link
Braiam
  • 4.5k
  • 13
  • 154
  • 265

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

... now suppose that it makes sense under certain conditions. Document it like so:

The following example is the Way™ you should approach X problems with a context of ABC

my code is a rainbow!

This is however is not recommended when ABCeither A B or C is not present when doing X due reasons

I believe that topics on Documentation should be comprehensive piecepieces of useful informations, and obviously you don't document anti-patterns unless they are useful. Through I believe that is attractive the idea of a "Don't's" section, is better to instead say "do it this way only when these conditions are present, otherwise do it this other way". Humans (that read) tend to react positively to these approaches, unlike when you restrict them.

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

... now suppose that it makes sense under certain conditions. Document it like so:

The following example is the Way™ you should approach X problems with a context of ABC

my code is a rainbow!

This is however is not recommended when ABC is not present when doing X due reasons

I believe that topics on Documentation should be comprehensive piece of informations, and obviously you don't document anti-patterns unless they are useful. Through I believe that is attractive the idea of a "Don't's" section, is better to instead say "do it this way only when these conditions are present, otherwise do it this other way". Humans (that read) tend to react positively to these approaches, unlike when you restrict them.

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

... now suppose that it makes sense under certain conditions. Document it like so:

The following example is the Way™ you should approach X problems with a context of ABC

my code is a rainbow!

This is however is not recommended when either A B or C is not present when doing X due reasons

I believe that topics on Documentation should be comprehensive pieces of useful informations, and obviously you don't document anti-patterns unless they are useful. Through I believe that is attractive the idea of a "Don't's" section, is better to instead say "do it this way only when these conditions are present, otherwise do it this other way". Humans (that read) tend to react positively to these approaches, unlike when you restrict them.

Source Link
Braiam
  • 4.5k
  • 13
  • 154
  • 265

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

... now suppose that it makes sense under certain conditions. Document it like so:

The following example is the Way™ you should approach X problems with a context of ABC

my code is a rainbow!

This is however is not recommended when ABC is not present when doing X due reasons

I believe that topics on Documentation should be comprehensive piece of informations, and obviously you don't document anti-patterns unless they are useful. Through I believe that is attractive the idea of a "Don't's" section, is better to instead say "do it this way only when these conditions are present, otherwise do it this other way". Humans (that read) tend to react positively to these approaches, unlike when you restrict them.