Improved shortcode docs

It's an underappreciated feature :) Took the API docs as a basis and extended it with an example and a bit more coherent language