Stop it! Stop Writing Unhelpful Help!

Is it just me, or is help becoming even more unhelpful than it has historically been?

Today I was creating a DataTable by defining DataColumn objects and wanted to prevent null values from going into a particular column. Presumably to do this, you would set the AllowDBNull property of the column to false. But to my memory at least, I’d never used this feature before (I lean more towards DataReaders personally — lighter weight and more performant for most of what I need to do, and people often seem a little DataTable happy to me … but I digress).

So … I wondered whether this prevents a row from being added to a DataTable’s Rows collection if it’s DBNull, or if it’s just “as info”, or something in between. No problem, let’s just look it up in help, right? Not! Here is what the docs say:

Gets or sets a value that indicates whether null values are allowed in this column for rows that belong to the table.

Um … yeah, I kind of figured that. No, wait! There’s more down under the syntax description! Surely that’s it!

Property Value

true if null values are allowed; otherwise, false. The default is true.

Er … gee, I would have never guessed.

The only useful info here is the default, which is not exactly a Big Surprise.

I don’t think this particular logic is in the Rotor source, as it’s part of ADO.NET, so I guess I’ll just write some tests to figure it out for myself, or just wing it. But for cryin’ out loud … this isn’t any better than saying the Text property of a TextBox contains the TextBox’s text, which can consist of any string value. I mean … what am I, some kind of dimwit?

I heard you in the back row — yes, you! The one that said, “apparently”. Guards! Take him away!

Ahem … now that we have that out of the way … pay no attention to the screams … let’s get down to cases, shall we? All of you in this room write help files, right? And help files are supposed to be … helpful, right? Helpful to whom, hm? To someone actually using the product, right? Right!

Now let me think … what would someone using the product want to know, and at what level?

I think we can safely assume that someone who can’t figure out that a declaration like “bool AllowDBNull” would have the values true or false, and that it tells us whether DBNull is allowed, is probably someone we don’t have to worry much about catering to. There’s no helping them anyway.

On the other hand, maybe … just maybe, mind you … your typical user might want to know at what point non-nullness is enforced, with a simple illustrative example with the most typical use case. That would tell the inquirer if it was designed primarily with the idea that it should work in concert with default values or not, for example. Maybe the likely answer is not that hard to make an educated guess about but maybe the inquirer would like to confirm that the person who designed the feature wasn’t on Quaaludes at the time, and just generally make sure the feature behaves as they expect. It should take 5 minutes to check out the help, which should be at least three times as fast as writing a test program (or a blog rant, for that matter).

That typical user might also want to know exactly what happens if you violate the constraint. Is the assignment ignored? Is an exception thrown? An error condition set someplace? Nuclear missles launched?

And, are there any exceptions to the enforcement of this rule? Any “gotchas”? Common mis-uses or mis-conceptions?

People, people people. People. For the love of all that is holy, don’t write placeholder help topics that you intend to flesh out later. You and I both know that you never will. Something worth doing is worth doing right.

That’s all. Go forth, and sin no more. And take care to step around that mess in the hall.

Oh, wait, there’s one more thing — you, the guy in the suit — you manage the help writers, yes? Come back. Sit down. Let’s chat. You needn’t tremble so!

Let’s be fair to the others who just fled … uh, left the room. I’m willing to bet that at least half the time when a gob of possum-snot like my example help entry on AllowDBNull sees the light of day, it’s because of someone like you (yes, yes, not you specifically, I’m sure, but someone a lot like you).

You see, the help author for that entry may have been trying to find out more about the feature, and they’re not getting any useful information. Your job as a manager is to remove obstacles in the path of your people getting things done. You are making sure that happens, yes? I thought so. Carry on.

What’s that? You’re curious about how AllowDBNull really works? Well here’s a snippet from a bug report to the Mono team that is illuminating:

+Summary: DataColumn.AllowDBNull mis-implementation
+
+DataColumn.AllowDBNull should not throw exeption on “existing” data.
+AllowDBNull (and Readonly) is only schema information, not for immediate
+data validation.
+Data should be valideted when a new value is given.
+
+This also how MS System.Data implementation works.

Despite the broken, mis-spelled English (don’t get me started) this indicates that an exception is thrown when someone attempts to assign DBNull.Value to the column. Probably a DataException, but who knows.

I wonder if the original author of the Mono implementation would have gone down that particular rabbit trail if he didn’t have to guess at how it’s supposed to work? I’ll bet he was working from the same “who cares” help file topic that we saw today.

Now away with you, and see to it that drivel like this cometh not out of thy department!