Documenting the Undocumented

Evolution of Documentation

Documentation is important, especially for the platform. Things that are used often, like xp_file_delete, need to be documented.

There are any number of functions in SQL Server that are undocumented. I have no idea how many there are because, well, they’re undocumented. I can’t see the source code, so I’m not sure what’s actually encoded in the platform.

I’ve heard arguments that everything should be documented, and while I appreciate the sentiment that complete documentation is a good thing, I also understand the other side. Each item that is documented must be supporter, or at least supported in the lawsuit happy US. That means it must also be tested extensively and this means an increased load on the resources available for SQL Server. While I don’t want to see testing limited, or quicker releases of the platform, I do want everything well tested.

There are some functions in the platform, such as some DBCC commands, that are added to help support. I can understand that testing, enhancing, and documenting these functions might not make sense. However I think there are some functions, which are used on a regular basis by millions of instances, and should be documented. For example, xp_delete_file is undocumented in Books Online, and a Connect item to provide documentation was closed as “by design”. However this function is called in maintenance plans, and has various bugs filed on cleanup issues and a lack of error reporting.

Paul Randal has a good blog on why DBCC commands aren’t documented and it makes sense to me. I agree with the overall philosophy, but I would like to see those features that are used in normal operation of the platform completely documented.

Steve Jones

The Voice of the DBA Podcasts

We publish three versions of the podcast each day for you to enjoy.

About way0utwest

Editor, SQLServerCentral
This entry was posted in Editorial and tagged . Bookmark the permalink.