Most of the documentation is based on the predicate that it will work but...


  • I have had many occasions that even the first step of a documentation which is supposed to offer guidance does not work. Should not the author of the documentation foresee this possibility? Presently I am facing a problem that the documentation has very little to offer.

    I think the documentation pages should have a comments section where users can freely voice their concerns. I remember to have worked with such a system using ColdFusion years ago

    Tuesday, March 08, 2011 3:38 PM

All replies

  • Hi Jayaram,

    I have a few thoughts about that, that I can share. But it can be nice to discuss concrete things, where you had problems and where changes could be nice.

    First of all it is always nice to have more community information inside. The MSDN Library offers "Community Content" which is not used that much as far as I have seen.

    The idea to have other solutions might be interesting but I fear that there are also bad sides ...

    a) Wiki - I think that is the best example for a documentation that the community might change at will. But in my eyes, the MSDN documentation is provided by Microsoft. I do not want others hacking in stuff that they might guess. I want the real information from the specialists. (Wikipedia is a good example where people fight about information....)

    b) Discussions on each page. It can be a nice thing. One site that comes to my mind directly is CodeProject.com which offers a discussion area after each article. But such an idea is not really usefull for the MSDN Library. It would simply split up the discussions. Where do you fidn the question / answer? You have multiple points where you can put it (e.g. on the class description itself or directly on a constructor or ...).

    So what do we have so far?

    - Microsoft runs a website for feedback and bug reports. connect.microsoft.com. This is a great site that helps microsoft to collect feedback and bug reports.

    - We have our forums with some main topics so it is much easier to find a good place for a question (And where the community can also easily find the questions that they might want to answer!). And I am a little annoyed, that Microsoft split all this up already. There are a lot of other sites like the app hub forums (formerly creators club), asp.net, windowsclient.net, Technet, ... I would like to have ONE location only. Then I could subscribe in the items I am interested in. (So at least I wouldn't like a split up of discussios on hundreds or thousands of pages inside the MSDN Library!)

    I am not sure, if that view was helpfull already. Feel free to write more about your ideas. As far as I know, Microsoft is really interested in feedback and I would always participate in discussions about topics what could be made better ...

    With kind regards,


    Thursday, March 10, 2011 12:00 PM
  • Let me cite a recent example the likes of which I have seen in some other cases as well.

    The documentation for publishing a LightSwitch application is deceptively simple,

    1. On Build menu, click Publish <Application Name>.

    The LightSwitch Publish Wizard appears.

    Now what if the wizard does not appear. It is true that the person who wrote the documentation tested and verified that the wizard appeared.

    Item 1 is what a non-programmer (one of the audiences for which this software is found appropriate) will start off doing and to his utter dismay it does not happen. How does he / she go about troubleshoot this one?

    I know it is a Beta product which is free but all the same....

    My suggestion is that there should be a comments section related to any documentation where the audience can point to difficiencies they notice. It is true that forum is there and it is indeed doing a great service but the priorities of the forum are not totally aligned with the documentation process. A Wiki is not a bad idea although you do not find it not very suitable. Wiki perhaps will edit the content, but a comment section would give some ideas to the person/persons who wrote the document so that it may be improved as long as all this happens in a civilized manner. The stake holders are (assuming it is a Microsoft product), Microsoft, documentation group and the intended audience.

    I would like to add that this documentation related problems are not specific to any particular vendor and is present in all and somewhat pervasive.  

    Thanks for the respose,



    Thursday, March 10, 2011 3:26 PM