I was reading a post that had this quote: " The MongoDB docs tell you what it’s good at, without emphasizing what it’s not good at. "

This isn't to pick on MongoDB, but the post did make me wonder what things SQL Server isn't good at? Should our docs, BOL specifically, have warnings about scenarios where there might be problems with code? In addition to the remarks section, should there be "Warnings" section about various features, functions and code? I image that the CREATE FUNCTION page might have some warning about scalar UDF performance in many situations, and I'm sure many of you would think of warnings that might be added for other features.

I understand Microsoft might not like to point out flaws, but in the interest of building better code and applications, shouldn't various versions of BOL, and perhaps all docs, warn the client about potential issues with using a feature in a certain way? Documenting the potential problems with using a feature in particular situations isn't a flaw; it's guidance about how misuse might introduce other issues.

It's not likely that we'll start seeing more warnings in the official documentation, but for those of you that would like to improve the situation for others, there are always the "Community Additions" sections on all BOL pages. I don't know if Microsoft would post your warnings there, but if they allow them, we might be able to help others understand the pitfalls of using a particular technique.