I agree with the "I prefer to use actual perl structures, named in a way that indicates what they should contain, ...". I would add the criteria/goal that the sample code should try to have a productivity advantage, i.e. allow cut-and-paste by the POD reader.
Try to use the standard/common variable names found in the shop or application in the sample code. Examples: return code ($retcode, $rc), error return ($error_msg), etc. to make the sample code easier to quickly use.