It doesn't talk about __pycache__.

FTR here's a link to the FAQ: http://docs.python.org/3/faq/programming.html#how-do-i-create-a-pyc-file

Here is a suggestion for updated documentation in this section. I've added the description of __pycache__, included a very short description of what a .pyc file is, and moved the troubleshooting to the end of the section.  I'm not sure whether the description ("a byte code cache file") is desirable here, but my sense is that people asking how to generate .pyc files are generally confused beginners.

Well, the FAQ entry is "why didn't a .pyc file get created", so presumably the querant knows enough to be looking for one to get created, and so presumably knows more-or-less what it is.

It seems to me that your rewording loses the sense of answering the question, and instead becomes more of a mini-tutorial on what a .pyc file is.

The changes needed here, it seems to me, are to talk about the __pycache__ directory instead of the .pyc file.  In python2, the issue would be that there was no write access to the source directory, and thus the .pyc file could not be created.  Now that same lack of access will first of all result in the __pycache__ directory not being created.

There is also then a second level: if the __pycache__ directory already exists but is not writable when a new module is first run, the .pyc file will not get created.  But I bet almost no one will notice that, and thus it won't be a FAQ :)  

Still, that issue could be mentioned...but then you also need to mention the full, two-part, version-specific extension, since one has to know which .pyc file to expect, if there are multiple versions of python on the system.  That mention could just be a pointer to the relevant docs, though, since most users will only be dealing with one python3 version.

I've had a stab at creating a patch for this.

As well as mentioning __pycache__, I've tweaked some wording to reflect the fact that .pyc files are regenerated if the source file's length changes (as per issue13645).

New changeset a14f830196ec by R David Murray in branch '3.3':
#18036: update .pyc FAQ entry in light of PEP 3147.
http://hg.python.org/cpython/rev/a14f830196ec

New changeset a757bdfce6b3 by R David Murray in branch 'default':
Merge: #18036: update .pyc FAQ entry in light of PEP 3147.
http://hg.python.org/cpython/rev/a757bdfce6b3

Thanks, A Kaptur and Phil.  I used Phil's patch, and added some additional tweaks and words.  (For example, I don't think PYTHONDONTWRITEBYTECODE existed when the FAQ entry was last updated).

I've chosen to maintain the existing flow, since it matches the title of the entry better.  It is quite possible, however, that the "question" is no longer in fact a FAQ, since most people probably don't ever look in the __pycache__ directory unless they are a distro maintainer.  It is possible what is really needed is a section of the docs that covers the actual implementation of PEP 3147 and all the associated issues surrounding .pyc files, but this updated version of the FAQ entry is at least an improvement on the status quo.