William (Bill) Vaughn's Musings

I agree wholeheartedly and I'll even say that it's infected the SQL Server Books Online. What used to be amazing documentation is now so slow and bloated that I only use it when I'm not wired (on a plane, for example).

I don't have any specific examples for you though but I hope people post some here and MS gets the picture :)

Ah, there's the rub. If we don't provide "repro cases", MS won't do much. If you see an example (egregious or not), just post it here. I'll try a repro and add it to the summary I'm sending MS. Otherwise it's all just hand-waving.

Thanks

Here is a typical example of where help was not that helpful. I expect the topic was generated by and for C# developers and anal ones at that.

I Tried to show how to create new data column from scratch. I selected DataColumn and pressed F1. After drilling into the DataColumn New constructor topic, the content indicated that I needed to pass a System.Type to the constructor using this syntax:
Dim typeInt32 As System.Type = _ System.Type.GetType("System.Int32")
Dim column As DataColumn = _ New DataColumn("id", typeInt32)
The problem with this two-line approach is that the strings to pass to GetType don’t seem to be documented and also seem to be case-sensitive—which is problematic for Visual Basic developers (they just don’t expect that behavior).
I’ve found that …
Dim dc As New DataColumn("ID", GetType(Integer))
works just fine. In addition, Intellisense in Visual Basic .NET helps pick the right type from a list of valid types. The Microsoft help topic did not say how to set the maximum length of strings, the default value or other ancillary (but important) Column properties like Unique or AutoIncrement that are typically captured by the dialog-based table code generators used to create tables on SQL Server.
The topic also did not really talk about anything but the bare mechanics of creating a new column. Perhaps there is another topic somewhere that does that but this one is fairly skimpy on practical information that developers should think about when creating new columns.
Suggestion: In the DataColumn New constructors, include code designed for Visual Basic that leverages Intellisense. If you insist on using the GetType(“string”) syntax, include a list of the valid DataType strings or how to generate them. I also suggest that you include content that shows how to set ancillary properties after the column is created. It would be nice if the New constructor included a couple of variations that worked for these common cases.
I also suggest a better, richer example. For example, this is excerpted from my book:
Private Sub CreateNewTable()
Dim dt As New DataTable("TeamRoster") ' Name the New Table
Dim dc As New DataColumn("ID", GetType(Integer)) ' Setup the PK
With dc
dc.Unique = True
dc.AutoIncrement = True
dc.AutoIncrementStep = 1
dt.Columns.Add(dc)
End With
Dim dcA(5) As DataColumn ' Create an array to pass to AddRange
dcA(0) = New DataColumn("PlayerName", GetType(String))
dcA(0).MaxLength = 20
dcA(1) = New DataColumn("DateAdded", GetType(Date))
dcA(1).DefaultValue = Now()
dcA(2) = New DataColumn("YearsExperience", GetType(Int16))
dcA(2).DefaultValue = 0
dcA(3) = New DataColumn("Caps", GetType(Int16))
dcA(3).DefaultValue = 0
dcA(4) = New DataColumn("SkillLevel", GetType(Byte))
dcA(4).Expression = "((YearsExperience +4) / 4) + Caps/5"
dcA(4).ReadOnly = True ' This is a "display only" column
dcA(5) = New DataColumn("Salary", GetType(Decimal))
dcA(5).DefaultValue = DBNull.Value
dt.Columns.AddRange(dcA)
' Display the new table in a grid to inspect and test it.
DataGridView1.DataSource = dt
End Sub
This illustrates several points in a single example. It shows how to add individual columns using the Add method as well as an array of columns using the AddRange method. It also shows a variety of data types and ancillary properties.

Here is a problem I just ran across:

I using the "Windows SDK documentation" from the June CTP release of .NET 3.0.

I set the "Filter" option to select only "Workflow"

I enter a search term of "persistence".

The first entry is the search result is for the Persistence classes of the ATL library for Visual C++.

Argh.

Here is a problem I just ran across:

I using the "Windows SDK documentation" from the June CTP release of .NET 3.0.

I set the "Filter" option to select only "Workflow"

I enter a search term of "persistence".

The first entry is documentation for the Persistence classes of the ATL library in Visual C++.

Argh.