SQL Clone
SQLServerCentral is supported by Redgate
Log in  ::  Register  ::  Not logged in

Is Documentation Dying?

The BOL for SQL Server 2005 has been interesting to read. On one hand there is a more comprehensive approach to documentation, but on the other, many entries lack substance. I've been in there a lot with book writing and after my editorial today, it hit me with Jamie Thomson's comments.

I completely agree with this. Just the other day in looking up the Execute T-SQL Statement task, I submitted feedback. It's a short task, basically a batch window to enter code and a timeout. However the BOL entry lists the timeout as being seconds before time. No mention of what 0 does (appears to be no limit), not mention of what happens to the task if it timesout. Testing shows it's an sp_reset_connection and a failure for the task, but obviously someone got tired of trying to document everything and short cutted.

Lots more entries like that and it's concerning. That along with another trend.

It seemed that lots of the SQL Server development started or worked on blogs during the development to build interest. Then surprisingly, quite a few of them released books. And now their blogs are rarely updated. It seems that the incentive to provide information has dropped. That along with the documentation problems means that there are quite a few gaps that are struggling to get filled with information. People like me trying to educate others are having difficulty determining how things actually work. Especially with too many white papers written against Beta 2 and not being updated.

I uinderstand the desire to sell books or other training. I know it's hard to rewrite stuff and make it a teaser to get people to buy your book. But the documentation seems to be suffering as well as the guidance from the vendor.

The Voice of the DBA

Steve Jones is the editor of SQLServerCentral.com and visits a wide variety of data related topics in his daily editorial. Steve has spent years working as a DBA and general purpose Windows administrator, primarily working with SQL Server since it was ported from Sybase in 1990. You can follow Steve on Twitter at twitter.com/way0utwest


No comments.

Leave a Comment

Please register or log in to leave a comment.