Providing Feedback about the SharePoint Developer Documentation (Uma Subramanian)


I’m a Content Publishing Manager at Microsoft responsible for the SharePoint Foundation 2010 and Business Connectivity Services developer documentation on MSDN. Our deliverables include the SharePoint 2010 SDK (published online and as an offline download), the SharePoint Developer Center, Technical Articles, and Visual How-To’s.

We would like to know what you think about the SharePoint 2010 developer content we’ve published out on MSDN so far. We are currently focused on identifying and filling gaps in our documentation set, as well as adding best practices guidance.

Here are some of the questions which may guide our conversation:

  • Is the current content set helpful?
  • What do you think are the biggest gaps in our content today?
  • What do you want to see more of? 
  • What can we do better?
  • We’re aware that developers simply love code samples and best practices. What areas would you prefer we target first?

Your input will help our team understand the current needs and prioritize our efforts accordingly. A number of us will monitor this post. I thank you for your time and look forward to your feedback!

-Uma Subramanian [MSFT]

Content Publishing Manager (SharePoint Foundation and BCS)


Comments (11)

  1. Robert MacLean says:

    – Is the current content set helpful?

    Yes, yes and yes.

    – What do you think are the biggest gaps in our content today?

    The biggest gap is the architectural planning. What is a content type (not technically but in terms of SharePoint usage) and where should it be used. Scenario based guidence may be a path to this but I think even high level architectural planning guidance would be beneficial.

    – What can we do better?

    Working with the million lines of XML is not fun because you have VS open giving a poor intellisense experience and you got to have a browser open to see the element defination on MSDN. Would be better to see the documentation integrated into the development experience.

  2. Andy Burns says:

    Is it useful – yes, very. It's definitely better than 2007.

    However, to try to give useful criticism, there are a couple of areas that could be better.

    Documentation of CAML isn't great. We're not going to get rid of it, so let's have it accurate and useful. For example the "BaseType" field on a list element (msdn.microsoft.com/…/ms415091.aspx) tells me nothing useful. What does it mean? How might I use it? Similarly with BaseViewID (msdn.microsoft.com/…/ms438074.aspx) – I've been trying to figure out exactly what that's for since 2008.

    Related: some of the nav could be better. Why are Features and Content Type Defs  second class citizens on another page to this one: msdn.microsoft.com/…/ms462365.aspx ? Why 'Other Schemas'?

    Secondly, some parts of the documentation seems to have been cut and pasted from 2007 – and it isn't always right – e.g. msdn.microsoft.com/…/bb802730.aspx

    All in all, better than 2007, but a B+ rather than an A. Oh, and some of the "HOW TO:" articles are just fantastic.

  3. Christophe Humbert says:

    It is great to see how the Microsoft documentation has evolved in the past few years, and the recent efforts to seek users' feedback.

    As an occasional developer focusing on the client side, I have two main issues.

    First, it is hard for me to find my way in all the available documentation. I don't understand the logic of having different locations. It would be helpful to have a "global site map".

    Second, I too often come across this message, especially when looking for Jscript samples:

    "This language is not supported or no code example is available."

    I'd like to see a clear statement instead; the Microsoft team should be able to tell whether the language is supported or not.

    Thanks!

  4. Robert, Andy, and Christophe,

    Happy New Year and thank you so much for taking the time to tell us the biggest gaps in our content and the things that bother you in the documentation we provide. My team and I currently are looking into the feedback we've received from you. We will get back to you shortly.

    Thanks,

    Uma

  5. @Robert, What kind of architectural planning are you looking for in the documentation? Is this more server topologies or planning a large software project? TechNet has some planning and architectural guidance here: technet.microsoft.com/…/cc288426.aspx Also, patterns & practices has documentation around designing a SharePoint application: msdn.microsoft.com/…/ff650022.aspx

    @Andy, Thanks for the feedback on that! We're trying to think of the best way to work through the CAML schemas. Right now, it simply serves as a reference point rather than actual code-based scenarios using CAML. Also, I'm personally working on getting that erroneous topic fixed. 🙂

    @Chrisophe, What, exactly, do you mean by different locations? Are you talking about the table of contents of the SDK or the split between MSDN and TechNet? Maybe something else entirely. 🙂 Also, I'm working with our teams on trying to change the text ("…language not supported…"). The text that you see is generated automatically when there is no code sample for a specific programming language. For example, all of the managed code can be in VB or C# given that it is .NET, but you will see that message if we didn't have time to create examples in both languages. It's a confusing message for sure and thank you for bringing it up!

    Thanks,

    Dallas

  6. Robert MacLean says:

    @Dallas – The p&p guidance is closer to my thinking, especially the Understanding Data in SharePint 2010 section.

    Where that falls short is that it doesn't go into much detail on the lighter topics and spends a lot of time on technical aspects (indexing, databases etc..).

    What I am looking for is a more guidance of when/where to use out of the box aspects of SharePoint. This isn't aimed at technical/developer architects but rather at system architects who have no idea what the DB layout is.

    For example: What is a content type (answered by the p&p guide)? What is the idea behind it's use? Some examples of good and bad uses of it?

  7. @Robert, I see what you mean. Have you browsed through the information in the SDK? We have a lot of high-level information and a few howtos on the topic of content types. You can see that here: msdn.microsoft.com/…/ms479905.aspx

    This doesn't necessarily provide prescriptive guidance on good and bad use of the feature since that will largely be based on implementation, but this should definitely help you with some of the higher level stuff that you referenced. Let me know if that helps!

  8. Dennis says:

    I like the documentation in some parts – in others there are big gaps. Let me give you some examples:

    – Lot's of "Available in SharePoint online" links, which overload the page (e.g.: msdn.microsoft.com/…/microsoft.sharepoint.spfield_members.aspx)

    – Large Parts of undocumented code (Visio Web Services + Workflows – how to create a custom visio diagram and link it up to your workflow?)

    – missing links between articles (e.g. msdn.microsoft.com/…/ms476062.aspx – TemplateType (what kind of types exist?)

    – Workflow related documentation is bad (e.g. how to create a workflow history list programmatically? The only official reference is msdn.microsoft.com/…/cc514224%28v=office.12%29.aspx for SP2007)

    – Basic Articles (good introduction for newbies) don't link to the more complete ones

    – Some part of the documentation was copied from 2007 and doesn't apply anymore

    These just off the top of my head – In general the documentation is better than the 2007 documentation, so you are doing a good job. However I would like to point out one major thing:

    – The comments to your MSDN articles are NOT read! Many times I see people writing stuff like "Code XY is wrong, please correct with YZ" – but nothing happens

    I don't know how you handle comments, maybe you have "owners" for articles and they don't check the comments very often? Make sure someone goes through the comments for articles, because many times there are good suggestions in them. If people feel you don't read them anyways, they will not comment (same goes for the small Feedback button – what about sending an email to the user giving the feedback like "we will take care of it"?).

  9. Dennis,

    Thank you for taking the time to provide feedback! It's really helpful. 🙂

    For the SharePoint Online point, the full object model isn't available in SharePoint Online. Based on that, we thought this information would be useful for those developers targeting SharePoint Online. Do you feel it is unnecessary clutter? How could we better display that the API is available in SharePoint Online?

    For Visio Web Services, have you looked in the Server SDK? msdn.microsoft.com/…/ff408345.aspx There are some examples there, but I will send your specific scenario feedback to the writer for that area.

    We have a lot of workflow-related documentation in the SDK here: msdn.microsoft.com/…/ms416312.aspx Do you have specific feedback for that area? I can pass that along to the writer as well as the feedback about the workflow history list.

    As a part of our process, we check comments monthly and incorporate actionable feedback. The only way we have contact information is if the commenter includes it in the comment. This makes it difficult for us to follow-up with our users. In general, we try to post a repsonse in the community content. You can see an example of that here from leswsmith: msdn.microsoft.com/…/ee539757.aspx

    Again, thank you for your feedback. It's always appreciated and helps us improve the quality of the SDK.

    Thanks,

    Dallas

  10. Dennis Gaida says:

    That was really a really fast answer – thanks for that! I think it is great that you are trying to reach out to the community this way – unfortunately not many people follow this blog 😉

    I understand you wanting to display the limitations of Sharepoint Online, but prepending *every* description with this text is really cluttering up everything (example msdn.microsoft.com/…/microsoft.sharepoint.spbasepermissions.aspx or msdn.microsoft.com/…/microsoft.sharepoint.splisttemplatetype.aspx).

    Taking the last example (SPListTemplate), you see that your tables might need another column (or two). I would suggest having a Description column, and a Sharepoint Online column with a checkmark for availability. If that is not an option – instead of writing "Available in Sharepoint Online" *in front* of the more important descriptions, write it after them. Secondly the text is too long – what's wrong with either using a small Logo for Sharepoint Online (green checkmark with Sharepoint logo or something – ask the marketing guys ;-). Sticking with the example you see that sometimes tables are in need of more columns. The "Value" for each SPListTemplate is written in the description, but would look better when in a new column.

    Immediate steps Write "Available in Sharepoint Online" AFTER the description. Things to consider: More columns (as it is tabular data), shorter text / icon usage

    About Visio: There is the Server SDK, but there is no mention on how to integrate Visio with *custom* visual studio Workflows (besides using Sharepoint Designer Workflows). There are some blog posts from smart people (e.g. blog.symprogress.com/…/adding-visio-diagram-to-existing-visual-studio-workflow-1) mentioning the usage of ShapeGuid's in the description of Workflow activities, but there is no documentation. So my request basically is to update the documentation on providing a custom Visio diagram for a custom workflow and how to link them together, so you have the same effect on "moving through the diagram" with each workflow step.

    Thanks for letting me know about monthly comment checking – I didn't know about that procedure and I like it very much.

    Dennis Gaida

    PS: SPBasePermissions (the above mentioned example). There is no explanation what each base permission *really* does. Compare "ViewPages" (View pages in a Web site.) and "ViewFormPages" (View forms, views, and application pages, and enumerate lists.) – how does "web site" relate to Sharepoint (so what are the pages on Sharepoint?) and what is meant with "enumerate lists" for the average user. On that page I think it would be good to provide further documentation on what exactly these permissions allow/disallow.

  11. Dennis,

    We're trying to get people to follow this blog. We've made this our one-stop shop for development blogging. If you build it, they will come? That's our hope. 🙂

    I just talked to the SharePoint Online writer, and he's going to follow-up with having those entries in the table removed or put into a table column. I'm also working with him on a solution for moving the first bit of text down. There are a few options here. We could move it down below the "Available in Sandboxed Solutions" line, combine the two "Available in Sandboxed Solutions and SharePoint Online", or maybe "Available in: Sandboxed Solutions, SharePoint Online". Thoughts on those ideas? We'll have to see about putting in the logo or check mark. Those are both good ideas!

    I see! Thanks for the clarification and link about Visio. I'll make sure our Visio writer gets the feedback.

    No problem! Glad you like the process. We try to take care of our users as much as possible.

    For SPBasePermissions, we do need clarification on the descriptions. I'll let our writer know about that and see if we can get some clarification.

    Thanks, again, for the feedback!

    -Dallas

Skip to main content