[Catalyst] IMPORTANT: To all Catalyst::Whatever Authors, please read and ACT

[Kieren Diment]

On 11 May 2008, at 10:56, Ashley wrote:

> Arguing that users who cargo-cult their configs from POD deserve  
> coddling and MODULE AUTHORS MUST ACT TO AVERT THIS DISASTER is silly.


No, users who don't understand how to use the code well enough that  
they have to rely on the documentation need documentation that won't   
confuse them with trivial stuff and unadvertised interaction bugs.   
YAML in pod causes these bugs, which impacts on the learning curve  
significantly, so please don't use it in documentation.  If you're  
still not convinced after reading  http://en.wikipedia.org/wiki/ 
Cognitive_load then I'm happy to these issues  off-list.

Your users are not you, they do not have your levels of  
understanding, and they are guaranteed to go about understanding  
things in a different way to the way that  you did.  Please keep  
their cognitive overhead to a minimum so they can realise their  
potential more quickly and easily.