David, I just posted a squishy comment on PEP 287. I realized that I can be more specific: PEP 287 describes a general-purpose structured text format "allowing for all kinds of documents." It doesn't say much of anything about docstrings specifically: "This PEP is not concerned with docstring semantics or processing at all." I think this is backwards. The PEP proposes to solve a specific problem -- docstring formats -- without any discussion of the problem domain or its requirements. Moreover, I disagree with goal 5. I think it is a non-goal to write a module's entire documentation in docstrings. (Perhaps it should be a goal that the docstring format is *not* right enough to write a module's entire documentation <0.6 wink>.) I think there two missing goals that are essential for a PEP that will make people happy: The first goal should be to keep the markup as simple as possible. The second goal should be to be targetted specifically at the needs of people who write docstrings for the standard library. I think it would also be productive to see an example or two of how this new format would be used in the standard library. Take a module that already has some decent docstrings and re-write it in the new format. Then we can see what benefit results from the effort. And take a module without docstrings and write new ones. (Some candidates: string, random, and unittest have good docstrings. getopt and hmac aren't bad. weakref is relatively small and doesn't have any docstrings.) If the primary goal is to keep the markup simple, I think it's impossible to judge a candidate without knowing what markup is required for docstrings. I am uncomfortable with the PEP's argument that "The problem is that a construct that seems superfluous to one person may be absolutely essential to another." A good design for a docstring format makes some hard decisions about what actually is essential and what is bloat. To paraphrase Aristole, wisdom comes from choosing wisely in the particular situation. Jeremy