Learn to use Visual Studio, Visual Studio Online, Application Insights and Team Foundation Server to decrease rework, increase transparency into your application and increase the rate at which you can ship high quality software throughout the application lifecycle
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 email@example.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.
David ChesnutContent Lead
Please put the Security section on top of each section that requieres it, and change the name to something like "Security Prerrequisites" or "Required Permissions". I recently installed TFS and I must say that I used to see the Security section when I completely finished all tasks. Sometimes I even didn't notice that section existed.
Results of feedback on how the "security" section in procedural topics can be improved.