18

I recently created this draft for the Python Polymorphism topic:

https://stackoverflow.com/documentation/python/drafts/61990

In it, I provided a basic example of polymorphism, and a counter example to demonstrate the value of polymorphism. The counter example shows some type checking that's necessary when polymorphism isn't used, resulting in extra code.

I see a lot of value in counter examples when explaining topics, but another user correctly pointed out that it may be confusing for users new to topics.

Are we okay with counter examples in Documentation, or should we avoid them to prevent confusion?

2 Answers 2

17

I think the counter example should be included within your right example. So the user know that the counter example go with this example and not another one.

If, with time, a lot of examples are added, it may not be so obvious to link the two of them together.

This can be see as an extension of Are multi-step examples wanted, in the documentation?. And the answer of this question is No.

1
  • Thanks for the link. I hadn't seen that question, and that's exactly what I did. I've amended it so both examples and the remarks are rolled into one example (the remarks really only applied to those examples anyway, not the general topic).
    – skrrgwasme
    Aug 3, 2016 at 15:46
0

Related to this is Best Practice. I see the Documentation pages as a good place to push examples that show the best way to do things. Sometimes this may be best phrased as "You could do it thus ...; but it would be better to do ... for these reasons...". Not quite a counter example, but similar.

Not the answer you're looking for? Browse other questions tagged .