Geeky Bob

I caught some people at work overusing some obscure acronyms in business emails that have considerably more popular uses, so I had to tell them to get used to spelling out phrases at least the first time in order to provide context for everyone else in the conversation. This should be obvious to everyone, but too many people fail to realize that their recipients may have no idea what the sender is talking about based on their individual knowledge.

For example:

• HTML - This should always mean "HyperText Markup Language," and it should never mean "Happy To Make Lemonade" With that in mind, you should always write "Happy To Make Lemonade (HTML)" when you first use it, and you should probably use it throughout your email. But still, you should consider writing "HyperText Markup Language (HTML)" when you first use it, just to make everything perfectly clear to your readers, and then you can use just the acronym for subsequent references.
• VS - This could be short for "versus," or it could mean "Visual Studio." Many English-speaking readers will probably be able to determine the correct meaning based on the surrounding text, but in a diverse work environment there is no guarantee that the intended meaning will be perfectly clear to everyone. This means that some recipients will have to re-read what the sender has written in order to verify their understanding, which could have been alleviated by simply using "A versus B" or "Visual Studio (VS)."
• OMG - This is often used colloquially to mean "Oh My Gosh," but I've seen it used to mean "On Middle Ground." Needless to say, the sentence can have dramatically different meanings depending on how that acronym is understood by the reader. For example: "Right now both parties are having a difficult time finding issues OMG where everyone can agree."

Social media acronyms should not be used in a business context; this includes the following examples:

• BTW - "By The Way"
• FWIW - "For What It's Worth"
• PDQ - "Pretty Darn Quick"
• SOL - "Sh** Outta Luck"
• etc.

There are a few possible exceptions which may be commonly-understood business acronyms, but you should still consider your recipients when deciding which of these acronyms you should use and which you should spell out. Here are a few examples:

• ASAP - "As Soon As Possible"
• FYI - "For Your Information"
• FAQ - "Frequently-Asked Questions"
• Q&A - "Questions and Answers"
• PS - "Postscript"

There is one simple rule that you should always remember when writing for others:

In business communications, brevity is not always better, and ambiguity will be the death of us all.

Publishing technical documentation is an interesting business, and a lot of discussion & deliberation goes into the creation process for articles and videos that we produce at Microsoft. For example, when I am writing an article for IIS, should I publish that on www.iis.net, or technet.microsoft.com, or msdn.microsoft.com? Or should I just write a blog about it? And after I have published an article, how will my intended audience find it? As we continue to publish hundreds of technical articles to the websites that I just mentioned, the navigation hierarchy becomes increasingly complex, and content discoverability suffers.

Some time ago a few of our writers began to experiment with a new way to consolidate lists of related content into something that we called a "Content Map." The following pages will show you an example of what the Content Map concept looks like:

• ASP.NET Deployment Content Map
• ASP.NET MVC 4 Content Map
• ASP.NET Data Access Content Map

Each of these articles received a great deal of positive feedback from customers, but our team wanted to see if there was a way that customers could help us to improve on this design. We know that there is a great deal of third-party content on the Internet, and we wanted a way to recognize that. We also asked several customers about what kinds of content they need to be successful, and we added their suggestions to our deliberation process.

As a result of our collective discussions, we came up with an idea for what we are internally calling "Curated Content Views." These "views" are lists of related content topics that are organized to answer a particular question or customer need. A view is assembled by someone at Microsoft based on input from anyone who thinks that an article, blog, video, or code sample might be beneficial as part of the view.

With that in mind, here are three conceptual content views that a few of the writers on our content team have assembled:

• How to deploy an ASP.NET web application to a Windows Azure Web Site using Visual Studio
• How to secure an ASP.NET MVC app
• How Do I Configure FTP Security in IIS?

Our team is requesting feedback from members of the community regarding these conceptual views with regard to the level of detail that is included in each view, the conceptual layouts that were used, and any thoughts about how this content compares with existing table of contents topics or content maps. You can reply to our content team via email, or you can post a response to this blog.

While we are interested in any feedback you may have, our team has put together the following list of specific questions to think about:

1. Each curated view/content map includes a list of suggested content links. Below is a list of additional information that could be provided with each link. Which of these are most important?
   • Date that the content was posted.
   • Type of content (video, article, code sample, etc.).
   • Author name.
   • Short description.
   • Level of difficulty of the content.
   • Version of software/framework or SDK the content refers to.
   • Website the content appears on.
   • Number of likes or positive reviews.
   • Rating assigned to the content by the community.
2. If you opened a page similar to one of these curated views/content maps from Google or Bing search results, would you be likely to try the links on this page or just return to search results?
3. If Microsoft and community experts published a large set of content views similar to these on a website, would you visit that site first when you had technical questions, or would you do an Internet search on Google/Bing first?
4. Do the questions addressed by each curated view seem too narrow or too broad in scope to be helpful? If so, which ones?
5. Do any of the curated views/content maps provide too much or too little detail for each link in the list? If so, which ones?
6. Do you find it helpful to see the profile of the person who created the curated view/content map?
7. If we provided an easy way for you to publish your own curated views (with attribution) to a common site together with the Microsoft-created curated views, would you be interested in doing so? Why or why not?
8. If we provided an easy way for you to suggest new content items to add to content views/content maps that have already been published, would you be interested in doing so? Why or why not?
9. What would make these content views/content maps more helpful?

Thanks!

Note: This blog was originally posted at http://blogs.msdn.com/robert_mcmurray/