Recently we noticed a trend as we’ve been reviewing all of the feedback sent in about various help topics. Occasionally an individual will be following a How to procedure, or walkthrough, and get stuck. We receive feedback explaining that a menu option was grayed out, or something was missing. Often the answer is that the individual did not have correct permissions, and furthermore, the permissions they needed were documented at the bottom of the topic in the “Security” section.

We worked hard to be sure that all Team Foundation How to and walkthrough procedures have the security section at the bottom explaining what permissions you need to successfully complete the procedures. So when folks get stuck and then don’t read the security section that would get them unstuck, we wonder what went wrong.

One thought is that maybe the word “Security” is confusing. We wonder if maybe this word makes people think of securing their code, or documents, and not of what permissions they need to get the tool to work correctly. As such, they skip over and don’t read the text. In this case we wonder if maybe there’s a better phrase to use like “Required Permissions” that would tend to catch the eye if you were stuck.

Another thought is that because the security section is at the bottom of the topic, people tend not to see it, or read it. You’re bound to get stuck if you don’t have the right permissions, and start following a procedure without reading all the way to the bottom first. In this case, maybe moving the security section to the top of a topic would help.

In this blog we are asking for your help and feedback. Do you tend not to read the security section? What would you do to improve the topics? Do you recommend changing the name of the security section, or moving it? Do you have other ideas?

Let us know by sending us e-mail at vstsuetb@microsoft.com. We’ll collect the feedback and follow up with a post later this month on the results. This is your opportunity to contribute to a change in the look of the content.

Thanks!

David Chesnut
Content Lead