I agree, and I suppose a lot of it is communication 101. Part of that is knowing your audience. You'd need to ask yourself a bunch of questions ("and you want to have them answered immediately!!").
* Who is your audience?
* Who do you want to be your audience?
* Are they technical or not?
* Are they familiar with the content?
* Are they native English speakers?
* Will non-native English speakers understand the communication?
I'm by no means an expert on this subject, so I'm unsure this list is complete.
I think these are all good points when it comes to writing technical documentation, but with naming things in code there are a different set of problems.
You can't hone your approach for a specific type of audience, because you can't make assumptions about who'll be reading it.
I think we can assume they're technical, and that they're proficient in the language the code is written in. Maybe we can't really assume they're familiar with the project, they could be new to it; but I think it's fair to say they're willing to be invested enough to become familiar.
--
The way we name 'things' in code, allows the reader to infer more about that 'things' place, contextually, within a larger structure.
* How can I indicate what this structure contains?
* How can I show why I have chosen this approach?
* How can I show how this section of code relates to the larger code base?
My default audience is myself before I started working on this problem. I assume general and technical knowledge, but little domain-specific knowledge and no knowledge of how the solution works.
Sometimes I'll target specific team members whose knowledge doesn't overlap mine well. Or I'll drop URLs for background info in block comments.
* Who is your audience?
* Who do you want to be your audience?
* Are they technical or not?
* Are they familiar with the content?
* Are they native English speakers?
* Will non-native English speakers understand the communication?
I'm by no means an expert on this subject, so I'm unsure this list is complete.