From How to Package Your LaTeX Package tutorial:
"The important parts of a package are the code, the documentation of the code, and the user documentation."
What is the difference between documentation of the code and user documentation?
Well, despite jjdb hit the spot with:
I'll try to be a little more poetic:
The user's guide, as its name implies, it is intended to be used by the user, i.e, the guy that sits behind the computer and uses your code to do whatever he needs to do.
The documentation code is part of the good practices a programmer follows in order to keep track of what he is doing, to leave clear messages for anyone who wants to touch the code and to keep his mind sanity (specially when coming back from long periods of no interaction with the code).
Basically, the user documentation should be as explicative as possible, since you don't know what is the level of understanding of the package of the person that is reading it (remember that if this is the first version, most likely nobody has ever seen it before), whereas the code documentation should be oriented to demonstrate what your code is doing and where it's doing it, so any modifications can be made as easily as possible.