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


Documenting the Undocumented


Documenting the Undocumented

Author
Message
Steve Jones
Steve Jones
SSC Guru
SSC Guru (63K reputation)SSC Guru (63K reputation)SSC Guru (63K reputation)SSC Guru (63K reputation)SSC Guru (63K reputation)SSC Guru (63K reputation)SSC Guru (63K reputation)SSC Guru (63K reputation)

Group: Administrators
Points: 63338 Visits: 19115
Comments posted to this topic are about the item Documenting the Undocumented

Follow me on Twitter: @way0utwest
Forum Etiquette: How to post data/code on a forum to get the best help
My Blog: www.voiceofthedba.com
GSquared
GSquared
SSC-Insane
SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)

Group: General Forum Members
Points: 23715 Visits: 9730
Agreed. This isn't a video game, where undocumented "easter eggs" are fun to discover. It's supposed to be an enterprise-level toolkit for managing data.

Imagine if you bought a toolkit from, for example, Sears, and it had some tools in it that you had never seen before. So you ask them what the tools are and how to use them, and the answer given is, "those are undocumented by design". The reaction? ... Yeah.

Now imagine that periodically, those tools automatically do things inside your toolkit. You don't know what, and are told to bug off if you ask the manufacturer. Kind of creepy, right? I mean, you could probably use that in some sort of C-grade horror flick (filmed on a WalMart video camera that has buttons on it that the manual tells you are "undocumented, use at own risk").

So, yeah, document this stuff. That's my take on it.

- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread

"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
chrisfradenburg
chrisfradenburg
SSCommitted
SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)

Group: General Forum Members
Points: 1988 Visits: 2067
GSquared (6/26/2012)
Imagine if you bought a toolkit from, for example, Sears, and it had some tools in it that you had never seen before. So you ask them what the tools are and how to use them, and the answer given is, "those are undocumented by design". The reaction? ... Yeah.


I think a better comparison are appliances where you start opening it and see something that says, "No user serviceable parts inside." You should be able to do pretty much anything you need to without cracking into that. However, there are going to be times that someone with extra training is needed to fix the appliance.

The more that's documented the more that we can reliably do ourselves so I am in favor of documentation. However, I understand the hesitation to put all the time into documenting DBCC page when they could be working on new features that are going to be used more frequently.
David.Poole
David.Poole
SSCertifiable
SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)SSCertifiable (7.7K reputation)

Group: General Forum Members
Points: 7715 Visits: 3287
Sounds reasonable in theory but there are some undocumented commands that have been around since the year dot. sp_msforeachdb being a case in point.

Perhaps in the old days not documenting stuff on an ROI basis had some validity but in the collaborative world who says that the documentation has to be written by central group?

At the moment there are all sorts of articles out there on how to use the undocumented commands but why not have a community contribution resource so the workload shifts from being "write documentation casting pearls before swine" to "verify documentation from the truffles that have been unearthed".

I think it is valid to have a documentation category that emphasises that the commands are for diagnostic and testing purposes and (while written by professionals) may contain nuts bugs.

The other thing I have to mention is that there is a M$ course which goes down deep into the SQL Internals and discusses how to interpret DBCC PAGE and others. I was one of five DBAs who came out of that course on day one feeling humbled and the colour of stupid worrying about the remaining 4 days on the course. To some extent these commands have been documented but the info isn't on general release.

LinkedIn Profile

Newbie on www.simple-talk.com
Revenant
Revenant
SSCertifiable
SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)

Group: General Forum Members
Points: 7383 Visits: 4864
In my experience, undocumented features are started as temporary solution that we "will visit and design correctly in the next release." If the "temporary" solution works, that never happens; however, the feature is already marked as "temporary" and "undocumented" and that is never revisited.
Miles Neale
Miles Neale
Hall of Fame
Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)

Group: General Forum Members
Points: 3060 Visits: 1694
I have to split hairs just a little on this one. If the undocumented feature can be run stand-alone that is one thing. But if it is something that is always intended to be used by the product internally or only used in certain instances and certain ways, that is another.

In the toolbox analogy if there are tools in the toolbox I agree the "users manual" should explain those tools. However if inside one of the electric tools in the toolbox there is a special mechanism that is unique to that tool and used only by that tool, it is undocumented and "under the hood". Just because someone could take that unit out of the electric tool and use it for something else does not mean that the maker of the toolbox is required to write documentation on it. The person taking the mechanism out of the electric tool assumes their own risk if they use the tool for what it is not intended to do.

But again if the tool is exposed stand-alone undocumented that seems odd and should be addressed.

Not all gray hairs are Dinosaurs!
Jeff Moden
Jeff Moden
SSC Guru
SSC Guru (87K reputation)SSC Guru (87K reputation)SSC Guru (87K reputation)SSC Guru (87K reputation)SSC Guru (87K reputation)SSC Guru (87K reputation)SSC Guru (87K reputation)SSC Guru (87K reputation)

Group: General Forum Members
Points: 87090 Visits: 41113
Although I'd love to see them document some of the currently undocumented stuff, what I'd really like to see them do is get the current documentation right and to spend some time fixing garbage functions like PIVOT which seriously falls into the "Nice try but you missed" category.

--Jeff Moden

RBAR is pronounced ree-bar and is a Modenism for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column.
If you think its expensive to hire a professional to do the job, wait until you hire an amateur. -- Red Adair

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
Steve Marak
Steve Marak
Grasshopper
Grasshopper (24 reputation)Grasshopper (24 reputation)Grasshopper (24 reputation)Grasshopper (24 reputation)Grasshopper (24 reputation)Grasshopper (24 reputation)Grasshopper (24 reputation)Grasshopper (24 reputation)

Group: General Forum Members
Points: 24 Visits: 192
I gave up on the undocumented extended stored procedures when a service pack broke the one that deletes backup files older than x and every maintenance plan based on the wizard started filling up hard drives. I use an ActiveX script to do tasks like that now. It's not pretty but it's mine and it works. It only breaks when the ActiveX subsystem does, and I hear about that right away.

I also don't like the thinly-veiled threat that the procedures may vanish in a future release of SQL Server. I suppose that is to scare off DBAs that might be rogue enough to call them without summoning the wizard.

It is nearly trivial to write T-SQL for making a transaction log backup of every database that isn't tempdb or set to simple recovery model. I call a stored procedure for those backups from a T-SQL maintenance plan task and it has three advantages over the wizard: 1) It doesn't try to log back up anything in the simple recovery model; 2) It picks up new databases so the maintenance plan does not have to be edited; 3) When the Cowboys in my environment who are too busy to let their DBA know there is a new database in an instance, and it is for x, and it needs to be cared for y, the failed transaction log backup within the next 4 or 6 hours lets me know someone is up to something...assuming the Cowboy isn't aware of the need to make a full backup of a new database (usually a safe assumption)...someone I will have a chat with soon.
GSquared
GSquared
SSC-Insane
SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)SSC-Insane (23K reputation)

Group: General Forum Members
Points: 23715 Visits: 9730
cfradenburg (6/26/2012)
GSquared (6/26/2012)
Imagine if you bought a toolkit from, for example, Sears, and it had some tools in it that you had never seen before. So you ask them what the tools are and how to use them, and the answer given is, "those are undocumented by design". The reaction? ... Yeah.


I think a better comparison are appliances where you start opening it and see something that says, "No user serviceable parts inside." You should be able to do pretty much anything you need to without cracking into that. However, there are going to be times that someone with extra training is needed to fix the appliance.

The more that's documented the more that we can reliably do ourselves so I am in favor of documentation. However, I understand the hesitation to put all the time into documenting DBCC page when they could be working on new features that are going to be used more frequently.


There's a big difference between telling a user "don't try to service your TV yourself, there are parts in there that can kill you, and you don't know which ones they are", and telling professional DBAs, "we can't be bothered to tell you how that works".

You know the TV ads and such that have the warning on them, "Professional driver on closed course"? Well, we are the professional drivers. And the pro mechanic team. And many of us are highly trained engineers on the exact subject at hand.

So I don't see it as comparable to "no user servicable parts".

- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread

"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
chrisfradenburg
chrisfradenburg
SSCommitted
SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)SSCommitted (2K reputation)

Group: General Forum Members
Points: 1988 Visits: 2067
GSquared (6/27/2012)
[quote]There's a big difference between telling a user "don't try to service your TV yourself, there are parts in there that can kill you, and you don't know which ones they are", and telling professional DBAs, "we can't be bothered to tell you how that works".

You know the TV ads and such that have the warning on them, "Professional driver on closed course"? Well, we are the professional drivers. And the pro mechanic team. And many of us are highly trained engineers on the exact subject at hand.

So I don't see it as comparable to "no user servicable parts".


And I don't see us as the end user of the appliance. I see us as the repair guy who knows what they're doing but doesn't have access to every schematic of every TV.
Go


Permissions

You can't post new topics.
You can't post topic replies.
You can't post new polls.
You can't post replies to polls.
You can't edit your own topics.
You can't delete your own topics.
You can't edit other topics.
You can't delete other topics.
You can't edit your own posts.
You can't edit other posts.
You can't delete your own posts.
You can't delete other posts.
You can't post events.
You can't edit your own events.
You can't edit other events.
You can't delete your own events.
You can't delete other events.
You can't send private messages.
You can't send emails.
You can read topics.
You can't vote in polls.
You can't upload attachments.
You can download attachments.
You can't post HTML code.
You can't edit HTML code.
You can't post IFCode.
You can't post JavaScript.
You can post emoticons.
You can't post or upload images.

Select a forum

































































































































































SQLServerCentral


Search