Help us help you!

  • Article

As my teammate, Cheryl, said a while ago in the Silverlight blog, we love your comments and the writer for each topic looks at the comments and uses them to improve the documentation. I have spent time this past month and a half going through your comments and making improvements based on your suggestions. We really do want to make our documentation useful, and with that in mind, I'm going to offer some tips about how to make your comments to use as useful as possible.

Be specific about what you don't like about a topic

Believe it or not, we writers spend a lot of time trying to figure out what information our customers need and how to best present it to you. We're aware that we often miss the mark, and that's why we rely on your feedback to make improvements. If you find a topic unhelpful, tell us what information you were looking for. Here's an example of feedback for the Drag and Drop Overview that is particularly useful:

This is disappointing because it doesn't tell how to start the drag, or how to create the targets' code to watch for the objects. The simple example is too simple and doesn't have any data object; the complex example (canvas/panel) is too difficult to dissect to figure out how to create the pieces needed.

This is great because it specifies exactly what the customer thinks is missing from the topic and why the samples we've provided aren't adequate. We can use this customer's input rewrite the topic to include the missing information and to change the samples to make them more useful and digestible. Conversely, we received the following feedback about the Controls Overview:

Been looking thru wpf for 10 hours and still not a good simple step 1 type example. You never get the correct balance on examples!

This is particularly distressing because I can appreciate the customer's frustration, yet I'm rather unsure of what they need from the examples. I could try to guess, but the topic already contains what I think our customers need to know about controls. I need to know what the customer is missing!

Finally, It probably goes without saying, but I will say it anyway, even less useful are cryptic comments that say only "No help." or "Worst thing I ever saw." (Both are real comments that I've received.)

Be aware that online feedback is anonymous

We sometimes get feedback asking questions or information. I always feel a bit dismayed by these because if the customer has provided feedback via the feedback link on MSDN's website (Cheryl's blog post show a picture), there's no record of who you are or how to reach you. For example, some feedback for How to: Create a ListView with Editable Cells says:

Sample is great but it does not update the underlying datastore (ie. the ObservableCollection); only updates the display in the listview. How do I get it to update the information stored in the collection after the edit occurs?

I'd love to give this person pointers to documentation that explains how to achieve what they want to do, but have no way to reach them. The best I can do is update the topic with links to the information they're looking for. If you want a response from us leave your email address or send us email at devdocs@microsoft.com. When you email us be sure to include the name and URL of the topic in the subject so it gets directed to the right writer.

If you have a technical question, the best place to get answers is the MSDN Forums. There are folks from the community there who can help you probably faster than we can.

Using Community Content on MSDN

A feature that was recently added to MSDN is the Community Content area at the bottom of each topic.

docwiki

This is a great way for our customers to contribute to the documentation. That's not to say that we're asking you to do our job. Rather, think of the community content as another way you can help each other. To paraphrase the Community Content FAQ the following guidelines should be followed when adding community content:

  • Do use the community content to add code examples and\or brief, useful pieces of information. For example, if a certain question about a particular API is frequently asked in the forums, adding the relevant comment to the API's topic is a great way to help out the community!
  • Don’t ask technical questions, add your opinions or carry on discussions here. The MSDN Forums is the appropriate place for these activities.
  • Don’t report product bugs to Microsoft; the community content is not monitored to find bugs. Use https://connect.microsoft.com/ instead.
  • Don’t report documentation bugs unless you are clarifying a potentially confusing issue to future readers. To report documentation bugs or request that further information be included in a topic, use the "Click to Rate and Give Feedback" link at the top of each topic or email devdocs@microsoft.com. And be sure to keep the points discussed earlier in this post in mind!

Carole