> "Public name" is a term that describes a convention, not anything enforced by the interpreter. 

And I guess that's really the main point. In other languages Public means accessible, and Private means not so.  In Python, Public means "suggested for outside consumption", and Private means not so intended, but nonetheless accessible. If that was reiterated near the discussion of __all__ it would be most helpful.  

>  Dirs mentioned in .pkg files *should* be added to the [...] pkg.__path__, not sys.path. 
> That could probably be made clearer, but the docs aren't wrong as they stand.

Again I've not managed to draw attention to the exact point of contention. 
1. A dir added to a .pkg file evidently should be an actual package dir.  
2. A dir added to a .pth file should NOT be an actual package dir. It should be the dir at the level above.

Thus the entries in .pkg and .pth files point to different kinds of things, yet the doc I pointed to asserts they are the same in this regard.