Recently I’ve integrated a tutorial on how to write an addon into blenders documentation.
This goes through from basics to taking an existing script, adding menu and keymap item and explains whats going on.
http://www.blender.org/documentation/blender_python_api_2_64_9/info_tutorial_addon.html
It also became clear to me that a lot the ways I often find out info when writing scripts are not obvious and needed to be explained.
http://www.blender.org/documentation/blender_python_api_2_64_9/info_api_reference.html
Thanks to John Nyquist for editing/feedback and Sebastian König who made me realize how non-obvious this stuff is 
Feedback welcome, if you want to make improvements the sources are here.
https://github.com/ideasman42/blender_addon_tutorial/blob/master/reference_api_usage.rst
https://github.com/ideasman42/blender_addon_tutorial/blob/master/readme.rst
