The person who reads your pod is the first kind of user. So just do your normal module documentation for him/her.

The second kind of user will read the documentation written by the first user. So you can add a "How to document your module" section in your pod. There you can tell your user what to say to his users.

I agree, it is a good idea to select some names and stick to them. It makes it easier to write documents and reduces confusion. I would suggests that the most important step is deciding to use specific names, which names you actually pick are unimportant (so long as everyone knows what you mean)

In one of my software systems we refer to:

• The "End User" who actually does the work
• The "Architect" who designs how bits go together
• The "Builder" who codes each bit

It sounds like your system won't quite match but this suits our way of working.

Another trick I have seen (but don't use myself) is to always mark out the name (say in italics) to remind readers that you are talking about a specific role when you use the name.

Hmm, in Cryptography, the names Alice, Bob, etc. are used. You set up the situation, and then use the names instead of "the sender" etc.

Without good succinct roll names, perhaps a sentence to introduce and explain the role of each Proper Name would make for a clear document.