Evan Goer: Thinking of Documentation as Code

As a software engineer, one of the best things you can do for your documentation is to take the principles of code construction that you already know and apply them to your writing. We'll demonstrate how thinking about documentation as code will help you avoid many of the classic high level mistakes people make when launching documentation projects. This is a companion piece to last year's talk, which focused on how to optimize English prose at the micro level.

[paolonestipoggi]

Nice talk.
However I disagree about the part about incorporating user comments into the documentation (the PHP way): Evan Goer highly underestimates the power of seeing the process of ideas being discussed, and actually seeing crappy ideas being rejected and on which grounds. In fact I think YUI documentation would take great benefit if users where able to write comments to the single methods and properties telling how they use them in practice. Lots of simple and repetitive questions would be avoided in the forum, a lot of frustration of first time users would be dispelled because they would get an immediate sense of how people actually use those methods, in practice, in  a way that even tutorials cannot accomplish, and with a much lower effort from the part of the core developers. They could instead use a bit of effort to correct or comment on some comments to put things straight when needed.