I have noticed that some CODEX pages contain a section on USAGE and others do not.

As a long-time programmer and relatively new (4 years) user of WordPress, I can say it would be much more useful for all if we could update all CODEX pages, particularly those on inherent shortcodes, so all of them have a USAGE section, and so that Usage Section would show absolute examples of the syntax for such usage.

As an example, in the Codex page on the [audio] shortcode, such a syntax example could look like this:

USAGE SYNTAX: Elements in (parentheses) are optional and if omitted will use the default value. Options are separated by the pipe | symbol. The first option is always the default option.

SYNTAX: [audio (src="path/filename.ext")|(mp3="~"|ogg="~"|wav="~"|wma="~") (loop="off"|"on") (autoplay=0|1) (preload="none"|"auto"|"metadata")][/audio]

EXAMPLES:

[audio src="www.mysite.com/audiofiles/myexampleaudio.mp3" loop="on" autoplay=1 preload="auto"][/audio]

[audio mp3="www.mysite.com/audiofiles/myexampleaudio.mp3"][/audio]

[audio][/audio] (Queues up the first audio file attached to the post.)

This sounds like a good idea, but I wonder if the syntax usage examples would confuse users into thinking that they actually need to write shortcodes like that. As developers it makes sense to us, of course, because we're used to seeing that kind of syntax explanation. But I wouldn't be opposed to giving it a try if you'd like to update some of the shortcode pages. More examples, where needed, would definitely be helpful. - Jdgrimes (talk) 20:41, 5 July 2017 (UTC)