New code samples in the Outlook 2007 Developer Reference!

MVP Helmut Obertanner contributed two new code samples recently in May:

• How to: Import Appointment XML Data into Outlook Appointment Objects
• How to: Obtain and Log On to an Instance of Outlook  

These code samples are presented in managed code (C# and Visual Basic). They are particularly interesting because they demonstrate the use of the .NET Framework Class Library together with the Outlook Primary Interop Assembly. "How to: Import Appointment XML Data into Outlook Appointment Objects" shows how to use the Microsoft COM implementation of the XML Document Object Model (DOM) to load and process appointment data in XML and return the data in Outlook AppointmentItem objects. "How to: Obtain and Log On to an Instance of Outlook" shows how to use Microsoft Language Integrated Query (LINQ) to verify if there is an Outlook process running on a computer.

You can view these code samples on the Office Online version of the Outook 2007 Developer Reference:

1. In Outlook, click F1.
2. Click the down arrow next to Search.
3. Under Content from Office Online, select Developer Reference if it is not already selected.
4. In the text box adjacent to Search, type a related search string such as "XML", "appointment", or "import" to find the topic "How to: Import Appointment XML Data into Outlook Appointment Objects".
5. Similarly, type a search string such as "log on" or "Outlook instance" to find "How to: Obtain and Log On to an Instance of Outlook".

Starting from this update, you can select from the TOC or search for the topic "Latest Additions to the Outlook Developer Reference" to see updates to the Outlook 2007 Developer Reference in the most recent quarter. Code samples from Helmut in the last couple of months are listed there.

As usual, you can also select from the TOC or search for the topic "How Do I ... in Outlook" which lists all the how-to topics in the Outlook developer help.

MVP Helmut Obertanner contributes code samples to the Outlook Developer Reference!

I am happy to announce that MVP Helmut Obertanner became the first MVP who contributed code samples to the Outlook 2007 Developer Reference on Office Online!

The two code samples that Helmut contributed are about the Account object, published in a new topic "How to: Send an E-mail Given the SMTP Address of an Account" and in the Account Object topic. These code samples are in managed code (C# and Visual Basic), which will directly benefit Outlook developers who have switched to using managed code over the last few years.

If you would like to see these code samples, they are available in the Office Online version of the Outlook 2007 Developer Reference. To view these code samples:

1. In Outlook, click F1.
2. Click the down arrow next to Search.
3. Under Content from Office Online, select Developer Reference if it is not already selected. This selection allows you to view the most current content in the Outlook 2007 Developer Reference on Office Online. This content is more up-to-date than the Outlook 2007 Developer Reference on MSDN.
4. Type account in the text box adjacent to Search.
5. Select the topics, “Account Object”, and “How to: Send an E-mail Given the SMTP Address of an Account” returned in the search results.

Typing other search keywords such as Helmut or MVP also returns these topics. Other than searching, developers can get to the new "How to: Send an E-mail Given the SMTP Address of an Account" topic via the following topics

• "How Do I... in Outlook" - lists this how-to topic in the list of how-to's in the developer reference

The following reference topics also list this how-to topic in the See Also section:

• Account object topic
• Account.SmtpAddress property topic
• Accounts object topic
• MailItem object topic
• MailItem.Body property topic
• MailItem.Recipients property topic
• MailItem.Subject property topic
• MailItem.Send method topic
• MailItem.SendUsingAccount property topic

I really appreciate Helmut's contribution, and anticipate to receive more code samples from him in the future. Go to Helmut's site at http://www.outlooksharp.de/ to find out more about his work!

BTW, at the moment, there is a small glitch on our publishing site that the URL of Helmut's site, http://www.outlooksharp.de/, is displayed not exactly as such but as the internal hyperlink we use to redirect viewers to Internet sites. Nonetheless, the hyperlink is clickable and brings viewers to Helmut's site, and our content engineering team is looking into fixing this glitch. Also, Helmut's code samples will be carried forward to the Developer Reference and Primary Interop Assembly Reference for Microsoft Outlook 2010.

Download for the Outlook 2007 MAPI Reference is now available!

You can now download the Outlook 2007 MAPI Reference from the Microsoft Download Center at http://www.microsoft.com/downloads/details.aspx?FamilyID=4b1b8b22-3c74-4479-bd0d-7b0ee29e8d59&displaylang=en!

Since my last blog post in January, it seems like the major search engines have made some progress on their crawling. When you search for some commonly used MAPI names today, like PidTagBody and IABContainer::IMAPIContainer, the more popular search engines return them on the first page of their search results. While the search engines are still working their way through the approximately 1500 APIs in the Outlook 2007 MAPI reference, you now have a choice to download this reference, install it on your computer in Compiled HTML (CHM) format, view it at your convenience, and search in this CHM file when you are not connected to the Internet.

The Outlook 2007 MAPI Reference documents about 950 properties in a considerable level of detail. The MAPI reference points you to corresponding Microsoft Exchange Server protocol documents if you need further information on most of these properties. If you often work offline, as in a controlled corporate environment, consider downloading the Exchange protocol documents and have them readily available on your computer as well. You can choose to download individual protocol documents or all of the Exchange protocol documents; currently there are 90+ documents available.

Where is the MAPI documentation?

Some internal partners and external customers have asked where to find the Messaging API (MAPI) documentation. Coincidentally, there were some updating issues on the MSDN server for a couple of days around the middle of the month, which caused corruption in the MSDN table of contents, looking for the MAPI documentation became a more frustrating experience.

The MAPI Programmer's Reference that the Microsoft Exchange Server group has supported for years on MSDN has been updated and republished as the Microsoft Office Outlook 2007 Messaging API (MAPI) Reference (http://msdn.microsoft.com/en-us/library/cc765775.aspx). About two years ago, the Exchange Server group decided that they will not continue to support the MAPI documentation. Microsoft Office Outlook, being a major MAPI client itself and having many of its customers developing MAPI solutions to work with Outlook, took over the MAPI documentation and updated it last year. The resultant documentation is the Outlook 2007 MAPI Reference, which focuses on developing MAPI solutions for Outlook 2007. There are now more current code samples and numerous additional MAPI properties. Content that is no longer relevant to Outlook 2007 has been removed. For what is new and what has changed, see What's New in This Edition.

For the next few months, if you click old bookmarks set up on a browser marking Web pages of the MAPI Programmer's Reference, you will see a short passage pointing you to the Outlook 2007 MAPI Reference and other alternative Exchange references. In the longer term, the redirection from the Exchange content to the corresponding Outlook content will be automatic. For the time being, set up and navigate using new bookmarks to the Outlook content. Some URLs have been specified in this blog for your convenience; in Internet Explorer, just right-click the link and click Add to Favorites.

As some of us are aware, new content on the Internet requires anywhere from weeks to months for search engines to crawl and index, before these search engines return this new content in customer searches. The Outlook 2007 MAPI Reference was published on December 3, 2008; if you search now, in January 2009, for specific MAPI interfaces, such as the following:

• IAddrProvider : IUnknown
• IAddrBook : IMAPIProp
• IMAPIContainer : IMAPIProp
• IMAPIProp : IUnknown
• IMAPISession : IMAPIProp
• IMAPIStatus : IMAPIProp
• IMAPISupport : IUnknown
• IMessage : IMAPIProp
• IMsgStore : IMAPIProp

Or any of the other 30 documented MAPI interfaces or 885 MAPI properties, you probably won't see results from the Outlook 2007 MAPI Reference ranked high on the list of returned results yet. Meanwhile, the way to look for documentation for specific MAPIs is to browse the table of contents on the left navigation pane of the MSDN Library. For example, if you are looking for a reference topic on a MAPI, and you don't yet have the Outlook 2007 MAPI Reference bookmarked, expand the following nodes in the navigation pane:

1. MSDN Library
2. Office Development
3. 2007 Microsoft Office System
4. Outlook 2007
5. Outlook 2007 MAPI Reference
6. Reference

Should the unfortunate event of last week's MSDN server update incident happen again, causing the Outlook 2007 MAPI Reference to temporarily disappear from the table of contents, feel free to send an e-mail to o12devdx@microsoft.com. Keeping our fingers crossed, with increased use of this documentation over the next few months, finding documentation on the Outlook 2007 MAPI Reference will become more efficient.

MAPI Properties and the New Outlook 2007 MAPI Reference

The Outlook 2007 Messaging API (MAPI) Reference is now officially published on MSDN! If you are interested in using MAPI to develop solutions that work with Outlook, take a look!

Microsoft MAPI specialist Stephen Griffin already talked about a few new features in his blog, so I’ll cut that short here. Being the project manager, I see the following as the few areas we spent most effort on and hopefully, by commenting in the Community Content at the bottom of a topic, you can let us know if the effort is worth it.

·         885 MAPI properties are now documented, including 452 tagged properties, some of which were previously documented in the Exchange MAPI Programmer’s Reference, as well as 433 named properties.

·         Overhaul of legacy content to remove outdated references of technologies and to fix bugs in the previous Exchange version.

·         New code samples showing how to create various Outlook items in C++ using MAPI and cross-referencing from concept, interface, and method topics into MFCMAPI to illustrate the use of specific APIs.

Looking for Properties? 

The Outlook 2007 MAPI Reference documents the majority of the properties that you would want to use in your Outlook solution.

Search keywords have been set up for each property topic to facilitate your search on MSDN, Windows Live Search, and other major search engines to retrieve the appropriate property topic in the Outlook 2007 MAPI Reference. However, depending on the crawls performed by specific search engines, during the interim period which can last anywhere from 24 hours to longer, your search for a property, like PR_BODY, may not yet return any result from the Outlook 2007 MAPI Reference. Mind you, the more you reference the Outlook 2007 MAPI Reference online, like blogging or discussing about it in your online community, the sooner your search engine will bubble up the appropriate results. Nonetheless, meanwhile, to reduce frustration, you can go to this topic to map your search to the appropriate MAPI property topic: Mapping MAPI Names to Canonical Property Names.

By the way, there is a small set of properties that we no longer support, and you can find the list here: Properties Deprecated in This Edition.

You probably have noticed that we now reference properties by their new canonical property names. For example, PR_ASSISTANT is now documented in the PidTagAssistant canonical property topic, dispidCategories in PidLidCategories, and EditTime in PidNameEditTime. Canonical property names provide a consistent way to identify and group completely identical or similar properties using one canonical property name. Over the course of MAPI history, properties with the same property tag, and properties with the same property identifier, but different types, have been defined for various reasons. For example, PR_BUSINESS2_TELEPHONE_NUMBER and PR_OFFICE2_TELEPHONE_NUMBER have exactly the same property tag (that is, their property identifier and property type are the same), and PR_SENDER_NAME, PR_SENDER_NAME_A, PR_SENDER_NAME_W have the same property identifier and different types. Now these two sets of properties can be identified by the canonical properties PidTagBusiness2TelephoneNumber and PidTagSenderName respectively. Note that canonical properties are not defined as constants in officially distributed MAPI header files, and you can continue to use real property names such as PR_BUSINESS2_TELEPHONE_NUMBER and PR_SENDER_NAME in your code. For more information on canonical properties, see MAPI Canonical Properties.

Remember, use the MSDN Community Content feature to provide your feedback!

We Get E-mails: Where Are the Object Members?

The object model reference documentation for the Office client applications (Word, Excel, Outlook, PowerPoint, Access, etc., etc.) provides detailed information about the associated properties, methods, and events for objects that are exposed through the API of each client application. This information is crucial if you develop applications that automate the client applications. You can find this documentation on both MSDN and within the help content that appears when you press the F1 key while using the Visual Basic Editor in one of the Office client applications.

The way this documentation is structured in the table of contents (TOC) in MSDN, the topmost topic node in the TOC is the object and under the main object topic node, you'll find the nodes for the associated  properties, methods, and events.

For example, this is how Word's Document object topic and associated member topics are arranged in the TOC on MSDN:

From there you can easily see that there is a node to a topic ("Document Object Members") that lists all the members associated with the Document object.

But sometimes readers are not browsing the TOC. They might get to the object's main page through a link in a search result or from some other web link. The object's main page looks like this (again using the Document object as an example):

So we get e-mails--"Hey! Where is the list of object members?" For one reason or another, many readers end up on the main page for an object and expect to see a list of the object's members. While there isn't a list of all the object's members on this page, there is a link to the topic that shows all the members for an object. Unfortunately the link is tucked away at the bottom of the page under the See Also section, so it's easy to miss:

Clicking the <Object Name> Object Members link takes you to the topic that shows you all the object's members:

The story is similar for the "F1" help documentation. The main object topic has a link at the bottom that takes you to the topic that lists all the members for the object. Here's the Word Document Object topic in the client help viewer (note the link to the Document Object Members topic under See Also at the bottom):

The link then takes you to the Document Object Members topic where you can see all the objects listed:

Office Chart Object Model in PowerPoint and Word

With the release of Service Pack 2 (SP2) for Microsoft Office 2007, you can now programmatically access and manipulate charts using the VBA object model in Word 2007 SP2 and PowerPoint 2007 SP2. Prior to Service Pack 2, you could only access charts using the VBA object model in Excel 2007.

The chart object in Word 2007 SP2 and PowerPoint 2007 SP2 is drawn by the same shared Office drawing layer implementation used by Excel 2007, so if you’re familiar with the charting object model in Excel 2007, you can easily migrate Excel VBA code that manipulates charts into Word 2007 SP2 and PowerPoint 2007 SP2 VBA code.

In Excel 2007, a chart is represented by the ChartObject object. In Word 2007 SP2 and PowerPoint 2007 SP2, a chart is represented by a Chart object. The Chart object is contained by an InlineShape or Shape (in Word 2007 SP2) and a Shape (in PowerPoint 2007 SP2). In Word 2007 SP2, you can use the InlineShapes collection of the Document object to add new or access existing charts. In PowerPoint 2007 SP2, you can use the Shapes collection of the Slide object to add new or access existing charts. You can use the AddChart method for both collections, specifying the chart type and location within the document or slide, to add a new chart.

You can use the HasChart property to determine if an InlineShape object (InlineShape.HasChart in Word 2007 SP2) or Shape object (Shape.HasChart in PowerPoint 2007 SP2) contains a chart. If HasChart returns True, you can then use the Chart property to get a reference to a Chart object that represents the chart. At this point, the implementation is virtually identical in Excel 2007 SP2, Word 2007 SP2, and PowerPoint 2007 SP2, and VBA code can be transferred across all three programs in most cases.

For example, the following VBA code adds a new 2-D stacked column chart to the active worksheet in Excel and sets the chart’s source data to the range A1:C3 from the Sheet1 worksheet.

Excel 2007 SP2

   1: Sub AddChart_Excel()

   2:     Dim objShape As Shape

   3:     

   4:     ' Create a chart and return a Shape object reference.

   5:     ' The Shape object reference contains the chart.

   6:     Set objShape = ActiveSheet.Shapes.AddChart(XlChartType.xlColumnStacked100)

   7:     

   8:     ' Ensure the Shape object contains a chart. If so,

   9:     ' set the source data for the chart to the range A1:C3.

  10:     If objShape.HasChart Then

  11:         objShape.Chart.SetSourceData Source:=Range("'Sheet1'!$A$1:$C$3")

  12:     End If

  13: End Sub

By comparison, the following VBA code adds a new 2-D stacked column chart to the active document in Word 2007 and sets the chart’s source data to the range A1:C3 from the chart data associated with the chart.

Word 2007 SP2

   1: Sub AddChart_Word()

   2:     Dim objShape As InlineShape

   3:     

   4:     ' Create a chart and return a Shape object reference.

   5:     ' The Shape object reference contains the chart.

   6:     Set objShape = ActiveDocument.InlineShapes.AddChart(XlChartType.xlColumnStacked100)

   7:     

   8:     ' Ensure the Shape object contains a chart. If so,

   9:     ' set the source data for the chart to the range A1:C3.

  10:     If objShape.HasChart Then

  11:         objShape.Chart.SetSourceData Source:="'Sheet1'!$A$1:$C$3"

  12:     End If

  13: End Sub

Key Differences Between the Chart object in Word 2007 SP2/PowerPoint 2007 SP2 and ChartObject object in Excel 2007 SP2

The Chart object in Word 2007 SP2 and PowerPoint 2007 SP2 does have a few differences from the Excel 2007 SP2 implementation.

• Programmatically creating or manipulating a ChartData object in Word 2007 SP2 or PowerPoint 2007 SP2 will cause Excel 2007 SP2 to run.
  
• Chart properties and methods for manipulating the chart sheet aren’t implemented.
  The concept of a chart sheet is specific to Excel 2007. Chart sheets aren’t used in Word 2007 or PowerPoint 2007, so methods and properties used to reference or manipulate a chart sheet have been disabled for those applications.
  
• Properties and methods that, in Excel 2007 SP2 normally take a Range object reference now take a range address in Word 2007 SP2/PowerPoint 2007 SP2.
  The Range object in Word 2007 SP2 and PowerPoint 2007 SP2 is different than the Range object in Excel 2007 SP2. To prevent confusion, the charting object model in Word 2007 SP2 and PowerPoint 2007 SP2 accepts range address strings, such as "='Sheet1'!$A$1:$D$5", in those properties and methods (such as the SetSourceData method of the Chart object) that accept Range objects in Excel 2007 SP2.
  
• A new object, ChartData, has been added to the VBA object models for Word 2007 SP2 and PowerPoint 2007 SP2 to provide access to the underlying linked or embedded data for a chart.
  Each chart has, associated with it, the data used to draw the chart in Word 2007 SP2 or PowerPoint 2007 SP2. The chart data can either be linked from an external Excel workbook, or embedded as part of the chart itself. The ChartData object encapsulates access to the data for a given chart in Word 2007 SP2 or PowerPoint 2007 SP2. For example, the following VBA code displays, then minimizes, the chart data for each chart contained by the active document in Word 2007 SP2:

   1: Sub ShowWorkbook_Word()

   2:     Dim objShape As InlineShape

   3:     

   4:     ' Iterates each inline shape in the active document.

   5:     ' If the inline shape contains a chart, then display the

   6:     ' data associated with that chart and minimize the application

   7:     ' used to display the data.

   8:     For Each objShape In ActiveDocument.InlineShapes

   9:         If objShape.HasChart Then

  10:  

  11:             ' Activate the topmost window of the application used to

  12:             ' display the data for the chart.

  13:             objShape.Chart.ChartData.Activate

  14:             

  15:             ' Minimize the application used to display the data for

  16:             ' the chart.

  17:             objShape.Chart.ChartData.Workbook.Application.WindowState = -4140

  18:         End If

  19:     Next

  20: End Sub

Open XML SDK 2.0 CTP Available

The Open XML SDK 2.0 Community Technology Preview (CTP) is here!

You can find the documentation for it here and the SDK download here.

Zeyad Rajabi, a Program Manager for the Open XML SDK, has begun a series of posts covering the Open XML SDK design goals and architecture, sprinkling in some sample code as he goes along.

Also, Eric White, a Microsoft Technical Evangelist, has a great write up on the new version of the SDK.

This new version of the SDK is an amazing leap forward.The Open XML SDK version 1 greatly simplified working with packages. Developers could manipulate Open XML file format compliant documents at the package and part levels using strongly typed .NET classes. To access the file formats at the element level, you still had to work directly with the underlying XML.

In the Open XML SDK version 2, the development team has taken most of the elements in the various schemas for the Open XML file formats (WordprocessingML, SpreadsheetML, PresentationML, etc., etc.) and made first-class managed objects out of them. Not to mention the fact that they've "linq-ified" the entire API so you have the power of Linq, as well.

This makes things much easier if, like me, working with XML directly isn’t your strong suit. With the Open XML SDK v2, I can work with objects that represent the XML elements instead of having to work in the underlying XML itself (although the SDK also supports LINQ to XML, as well). For instance, suppose I needed to locate the first table in a Word document. I could easily locate the first table present in the document with code like this:

   1: using (WordprocessingDocument theDoc = WordprocessingDocument.Open(location, true))

   2: {

   3:     MainDocumentPart mainPart = theDoc.MainDocumentPart;

   4:  

   5:     Table theTable = mainPart.Document.Descendants<Table>().First();

You can see the advantage of using this new version of the SDK in line 5 of the code snippet where, by specifying that I want to filter for descendants of the Document object (which represents the <w:document> element in the Microsoft implementation of the Open XML WordprocessingML) where the descendant is of type Table (that is, I want all <w:tbl> elements), I can immediately get to the tables in my Word document.  Then, by using the First() extension method, I can select the first table element in the returned list of descendant table elements. All without having to do the detailed work of traversing the underlying XML directly; the API handles the XML work for me.

Or how about trying to get to the text in a specific cell in the Word 2007 table? I’m simplifying things a great deal, but let's assume I know which cell has the data I want (the cell in the 2nd row and 1st column):

   1: TableRow theRow = theTable.Elements<TableRow>().ElementAt(1);

   2:  

   3: TableCell theCell = theRow.Elements<TableCell>().ElementAt(0);

   4:  

   5: string cellText = theCell.InnerText;

   6:  

   7: Console.WriteLine("The 2nd row, 1st cell text is {0}", cellText);

So here I just use the same technique that I used above to find elements of a given type (by using the provided generic methods) in order to find the 2nd row of the table (<TableRow>().ElementAt(1)) and the first cell (<TableCell>().ElementAt(0)). Then I just pull the value of the Cell object's InnerText property and it's done! Although there are other ways to use the SDK to get the same data, you can still see that with only a few lines of code, I'm able to do quite a bit without working directly in the underlying XML. And remember, we can do this type of manipulation WITHOUT running the client application (in this case Microsoft Word 2007).

The Office Client Developer Content team (my team) has some great examples on the MSDN web site here. Check it out!

Open XML SDK 1.0 Available

Just read fantastic news from Erika Ehrli Cabral that the Open XML SDK 1.0 is now available. She writes:

"The Open XML Format SDK Technology Preview simplifies the task of manipulating Open XML packages. The Open XML Application Programming Interface (API) encapsulates many common tasks that developers perform on Open XML packages, so you can perform complex operations with just a few lines of code. Using this API, you can programmatically generate and manipulate Word 2007 documents, Excel 2007 spreadsheets, and PowerPoint 2007 presentations. The programming model uses managed code, so it's safe for server-side scenarios.

The Open XML Format SDK also provides how-to articles and reference documentation that can help you get started with Open XML programming."

See her post for details on where to download.

Open XML Format SDK April CTP

Erika has a detailed post on the new release of the Open XML Format SDK, as well as the future of the SDK. The Client Dev Docs team is looking forward to creating the new components (Version 2.0, below) of the SDK over the coming year.

Did you know???

Did you know that if you double-click on a non-linked word in a NYTimes.com article, it will open a new window with a definition of that word? Neither did I until I accidentally doubled clicked a word trying to select it today. Nice!

New Excel Development Blog

Usage Analysis of the Access Developer Reference

The 2007 Microsoft Office System was released into the wild about a year ago. I’d like to share what we've learned about your usage of the Access 2007 Developer Reference since its release. BTW, I'm Mike Stowe, the programmability writer for Access.

The data that drives this analysis comes from users who are in a "connected" state while using the Access Developer Reference. When you're in a connected state, help topics are being served to the Help window from Office Online. This is the first time we've had the opportunity to collect usage data and comments from our users. David Hale's Let's Talk about Office VBA Help post contains more information about this connection and how it benefits everyone.

I'll begin by borrowing a chart from David's post. It summarizes the total page views for the top Office 2007 developer references.

I never tire of looking at this one. The Access topics receive, by far, the most views. The Excel and Visual Basic Core topics are also utilized fairly often. We've always known that the Access Developer community was large, but this is the first time that we've had data that compares the relative usage of each content set.

Note that the chart doesn't contain the actual number of page views. I can't share any specific numbers with you, but I hope that you find this analysis useful without them.

The Access Developer Reference is made up of several components. The Access object model help is the core component of the developer reference. Help for DAO, ADO, the Access SQL functions and the Access error messages are the other components included in the Access Developer Reference. In earlier versions of Access, the help topics for each of these components were scattered on your hard disk in separate .chm files. In Access 2007, we unified the components into one browsable, searchable unit.

The next chart breaks down the usage of the Access Developer Reference by component.

This chart reveals the single biggest surprise of our analysis. The error topics make up 1/3 of the page views! We had NO IDEA that this was the case. I'll discuss the ramifications of this finding later when we examine the most-viewed error topics.

Object topics

Which individual topics are used the most? Let's start by examining the top 20 object or collection help topics in the Access Developer Reference.

DoCmd. Form. Application. ComboBox. That's pretty much what I expected to see at or near the top of this chart.

Member topics

Next, let's take a look at the top 20 member topics.

The first thing you'll notice is that the most view topic, DataType Property, isn't part of the Access object model. This topic appears when you press F1 in the Data Type column while in table design view. It's also the most-commented topic outside of the error topics

I don't see any surprises among the actual object model topics in the rest of the chart.

Error topics

Now, let's examine the top 20 error topics.

As I said earlier, I can't share specific numbers, but the top three error topics tower over the rest of the topics in both page views and comments. The interesting data is in the comments left for each topic rather than the page views.

The comments reveal that the topics aren't appropriate for the audience. The topics contain developer-focused terminology such as "Null" and "primary key". The topics were written for a developer who would likely understand the issue and trap the error before it surfaces to their user. Most of the comments appear to come from information workers who just want to make their form work!

I'm going to start addressing these problems by rewriting the topics for the top three errors in a way that will better serve an information worker tasked with using an Access form.

Comment Analysis

The page view data is a useful for spotting usage trends, but comments are much more useful for improving individual topics. Examining all of your comments has revealed the following points:

• The top error topics have been, by far, commented on the most.
• The DataType Property topic has many people asking about data types for items such as phone numbers and social security numbers. The topic should be modified to clearly explain the relation of a field's Format and Input Mask properties to its data type.
• The ValidationRule topics need many more examples.
• The new help layout has spawned a couple of common usage issues. You should take a moment to view Quick Tips on using VBA Help with Office video if you've ever wondered why there isn't a table of contents or where to find a list of properties, methods, and events for a particular object.
• There have been 84 specific "How do I?" requests.
• 74 topics contain a general request for code sample.

Most of the topics never reach a critical mass of comments, so the "How do I?" and code sample requests indicate where we should invest our time and resources.

The Bottom Line

The data clearly indicates that the top error topics should be rewritten. I'm working on top three error topics right now.

The DataType Property topic would be more useful if it better explained the relationship between a field's DataType, Format, and Input Mask properties. That's on my to-do list.

I'll prioritize and address "How do I?" and code sample requests as time allows. Requests that touch on the most-used object and members receive the highest priority.

I'd love to hear from you if you have any questions or comments about the Access Developer Reference.

Microsoft Office Excel 2007 VBA Reference Feedback

Greetings.

My name is Rod Chisholm and I am the Programming Writer for Excel client VBA (Visual Basic for Applications) and Programmability. Our reference material is available in the box, on MSDN, and NOW on Office Online. This gives us the unique opportunity to gather ratings and feedback from our users to help strengthen our topics, and improve the help experience overall. As my manager, David Hale pointed out early this month in Let's Talk about Office VBA Help, Excel is ranked in the top three for hit counts on Office Online. So we are certainly getting traction and visibility. From all those hits approximately 1 out of 100 leaves a rating. Of those, about 1 out of 5 leaves a comment. With comments, there is less guess work as to why a topic gets attention, so the more, the merrier.

Are we listening?

Yes we are! For those who think that comments are dropped into a black hole, let me assure you that I have reviewed all the data and comments since the launch of Office 2007. Although there were a vast number of comments, most could be categorized in five or six areas. The areas of interest to me were the requests for codes samples, and the “how-to”, or “how do I” feedback. Both are key indicators that the reference material in these areas should be where time is invested. So, thank you for participating. You are making a difference.

 Here is a breakdown of some trends and areas of focus for content improvement, based on site hits and your comments (special thank you to Mike Stowe, Access Programming Writer for help with data analysis):

Top Object Hits

Huge generators of site hits include Range, Application, Worksheet, Sheets, Workbook and Worksheets to no surprise. These Objects are used most frequently and essential to workbook navigation. 

Top Member Hits

To me it looks like a pretty even distribution of hits, but the common denominator here is Range making up 10 of the Top 20. Range will be a primary focus for content ideas moving forward.

Top "How to" Topics

The bottom line is that Range and how to navigate within a worksheet seem to be the heavy favorites when it comes to hit counts and comments. So, look forward to content improvements, more code samples and additional topics around hot areas of Excel. Until next time, please keep the feedback coming. I'm listening.

For more information check out the Excel Developer Portal and the Excel Team Blog.

Please post a comment if you have any questions or concerns.

Cheers.

RdC ~Excel

Outlook 2007 Developer Reference updated on MSDN!

The Outlook 2007 Developer Reference has been updated on MSDN on November 13, 2007! This Reference contains conceptual, reference, and programming task topics, guiding developers to program Outlook using the Outlook Object Model. This is the first update to the Reference on MSDN in ten months since January. Over the last ten months, more than fifty improvements and fixes involving hundreds of topics have been applied to this set of documentation. The following  are some of the areas of improvement:

-       Search and Filter – Clarified certain concepts about DASL and Jet queries, added new code snippets and programming task topics, including Filtering Items Using a String Comparison, How to: Search the Calendar for Appointments Within a Date Range that Contain a Specific Word in the Subject, and How to: Search the Calendar for Appointments that Occur Partially or Entirely in a Given Time Period,

-       Enumerating, Searching, and Filtering Items in a Folder - Clarified how to obtain a writeable object from a row in a Table that supports read-write operations.

-       AdvancedSearch method of the Application object – Clarified the limit of simultaneous searches.

-       Address Book – Added a new programming task topic How to: Map a Display Name to an E-mail Address.

-       Items, Folders, and Stores – Added a new programming task topic How to: Delete All Items and Subfolders in the Deleted Items Folder.

-       NewMailEx event of the Application object – Added precautions to take when obtaining the Entry ID of the new item.

-       OlUserPropertyType enumeration – Supplemented the constants in the OlUserPropertyType enumeration with corresponding MAPI type values. For example, the constant olDateTime maps to the MAPI type PT_SYSTIME.

-       Automating Outlook from a Visual Basic Application – Clarified the security reason for a VBA application to use the trusted Application object intrinsic to the environment, except when the application intends to automate a separate instance of Outlook. All code samples in the Reference have been scrubbed to reinforce this concept.

I would like to thank Outlook MVP, Sue Mosher, who over the last year helped us improve our documentation by going through a large volume of the topics in the Outlook 2007 Developer Reference and giving us valuable feedback.

In case you are wondering, ten months seem to be a long time to wait for an update, the client applications of 2007 Microsoft Office system are capable of continuously refreshing developer reference content through Help in the product when you select to search and obtain content on Office Online! Through this mechanism, all the improvements and fixes included in this update on MSDN were actually already pushed on Office Online within a day after the corresponding topics had been modified. If this sounds novel to you, stay tuned, I will talk more about this next time.