11

In the Python documentation, there is a requested topic for PEP8. For those that aren't aware, this is the style guidelines for Python. The official guidelines contain examples of what code should and should not look like.

Is re-documenting this kind of information the intended purpose?

3
  • 4
    I will calmly leave this link here, yes this one Would it be wrong if I get my example from Google's dev page for the documentation?
    – Braiam
    Commented Jul 21, 2016 at 15:36
  • 1
    Ugh... it was created..
    – Braiam
    Commented Jul 21, 2016 at 15:37
  • 1
    "This document gives coding conventions for the Python code comprising the standard library in the main Python distribution." PEP8 is intended only to describe the rules for a particular source base, not the rules for correct Python. Is "how to write code for a particular specialized source code base" something that SO Docs really needs to cover?
    – librik
    Commented Jul 22, 2016 at 6:47

1 Answer 1

7

Remember that the goal of docs is making sure developers have documentation that serves them well. When it comes to pretty much any part of how a language is explained, you can ask:

  • Is this easy to understand? Can I read this and just go do what it's explaining?
  • Are there common pitfalls that I and others fell in because the 'wrong' way wasn't well explained?
  • Can someone working on real-world stuff relate well to the examples?
  • Is the reasoning behind things explained well where it needs to be?

.. if the answer to any of that is "no", then make something better :) If it's all "yes", then there's not really much to do.

1
  • 5
    But what if someone else is creating the topic although the answer is no? Should we then delete it or let it stay? Commented Jul 22, 2016 at 9:11

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