I would just like to point out that you didn’t test the working programmer experience here, but the newcomer experience. As such I find the title of your post and conclusions a bit misleading.
It is a common mistake among system designers to optimize for beginners rather than the working user; ideally both should be as well served but there is a tension (which is where all the interesting design choices lie btw.). As your introduction mentions we have anedoctical evidence that opam works very well for many working programmers which is already quite encouraging.
It seems we now have anedoctical evidence that it works less well for newcomers and we should try to streamline all this, including the documentation. However I’m not too “alarmed” by the result of this. Good software takes time to produce and as @bluddy mentions by the time you’ll be ready to publish something you might be a little bit more familiar with the surrounding tools.
In any case I do not want you to think that no one cares about these issues. In the platform project we are constantly trying to devise new tools and workflows to improve the eco-system experience and this includes lowering the barrier to entry to publish packages.
Here’s a working prototype worfklow that relies on unreleased experimental software (so there are a few extra steps below and still a few rough edges in the out of the box experience, this is just to show you). Assuming you are using github to publish your software the following takes you from project setup to versioned publication on the OCaml opam-repository:
opam pin add carcass https://github.com/dbuenzli/carcass.git
opam install publish topkg topkg-care
carcass setup # Answer the personal questions
git clone git@github.com:user/mypkg.git && cd mypkg
carcass body topkg/pkg . && git add . && git commit -m "First commit."
topkg tag v1.0.0
topkg bistro
# You are done
But this still need a bit more work before everyone gets to use this. Note however that the topkg release workflow (see topkg help release) is already available for anyone to use (and the whole thing if you are not bothered dealing with unsupported software, I am so I generally advise against this).