What Makes a Good Technical Article

So we have a particular error in SharePoint and two articles online about how to resolve it. These two articles are exceptional examples of good and bad ways to write a technical article. What makes the “bad way” such a great example is that it’s bad in the very subtle way that technical articles can be. It’s also a perfect textbook example of why I always need to rein myself in when I want to rush off to write a technical article.

Here is the first article:

“The given key was not present in the dictionary” issue in SharePoint 2010 RTM (alipka)

It seems to fairly straightforward. But if you try to correct the issue, you’ll see the author gives the fix:

I had to grant AUTHENTICATED USERS READ permission (probably read ‘some’ information would be enough) to the MOSS accounts (I granted to the DB access account and managed services account). After that an IISRESET and it worked.

Easy enough. Let’s just go take care of this. I just have to grant authenticated users read permission to some accounts. Okay.

… where? SQL Server? SharePoint? Local users and groups? There’s mention of an IISReset – maybe somewhere in IIS? Nope. Where?

Reading through the comments, the author mentions the Security tab in Active Directory Users and Computers. Ah. So I go to a domain controller I have handy and open a user account in the applet:

User dialog in Active Directory applet.

User dialog in Active Directory applet.

No “Security” tab. [sigh] Okay, let’s take a look at another article on the same subject:

The given key was not present in the dictionary Error when Validating User Accounts (blogs.technet.com)

Here the author walks through eight simple steps that explain where to go and what to do. (And we find out quickly that yes, it’s in the Active Directory Users and Computers snap-in, but that you have to enable Advanced Features to get the Security tab…)

Any time you’re posting a technical note, how-to, or walkthrough, make sure to copy exactly what your end user is going to have to do. I can’t tell you how often I’ve walked through the steps myself and discovered I assumed some part of the procedure that an end user would have issues with. (Another classic “Oops, did you need to know that?” is neglecting to note referenced assemblies, include files, or utility classes)