Printed 2017/08/16 09:41AM

Is Documentation Dying?

By Steve Jones, 2006/03/24

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.

Copyright © 2002-2017 Redgate. All Rights Reserved. Privacy Policy. Terms of Use. Report Abuse.