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.
_______________________________________________ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
