First of all, I understand your points. I also get a little frustrated by documentation in certain areas of the product (VS Extensibility docs are frustrating me at the moment) - one of the reasons that I add Community comments to the bottom of the page when I see something missing.
However, despite what it looks like on the outside, documentation is a priority, both on the content side and infrastructure side of things (Lightweight view is a perfect example) There's a couple of reasons why the docs are sparse, lacking examples, or just bad: 1) There's a lot of it. .NET Framework's surface area doubled between 3.0 and 4.0. Whether that's a good thing or not is in the eye of the beholder, but it makes it especially hard to write good docs on all members. 2) Developers aren't doc writers. While I do see some good XML comments written by developers internally, it's usually a rarity - and spending time on this means less features. Less features means complaints about missing features. It's a catch-22. 3) On some teams the doc writers don't have a lot to do with the feature team. While not true on my team (BCL) where the doc team turns up to every spec review & team meeting, other teams I've been on the doc writer lives in a completely separate building and doesn't get involved until after the team is feature complete. We do need to improve on this. 4) It's not worth the return on investment to heavily doc every single member. As mentioned below, there's over 200,000 pages on MSDN, some with under 10 pages view total. We need to make sure we make the right call around what members people are having trouble with and what members need examples. However, we're also continually updating the docs every month. For example, we recently overhauled the String<http://msdn.microsoft.com/en-us/library/system.string> class docs last year, this is despite this class practically not changing for over 5 years (I think we added a couple of methods in 4.0). Please also don't get me wrong, I'm not trying to make excuses, but rather trying to be honest. Although I can't directly impact the docs as a whole (other adding comments to them where I can, and making sure my feature's docs are good) - I will forward this thread onto a couple of people who can impact them. From: ozdotnet-boun...@ozdotnet.com [mailto:ozdotnet-boun...@ozdotnet.com] On Behalf Of Stephen Price Sent: Wednesday, March 23, 2011 7:26 PM To: ozDotNet Subject: Re: Raising property changed events Assuming around 200 people on the list, if we each take 1000 pages we should be able to tag them all with a "please provide examples" I get what you are saying we can post on the pages asking for improvement. Doesn't help you at that moment. It does show that documentation wasn't a priority. Someone wrote the code once how come that person, or someone following closely behind didn't document this public facing class/method When it was written? Going back and documenting it all now is a mammoth task. Technology is being invented at a pace faster than you can learn it, we need to be making it easier to learn not harder. Agree with Grant. This is an opportunity to really shine. On Thu, Mar 24, 2011 at 7:38 AM, Trevor Andrew <tand...@tassoc.com.au<mailto:tand...@tassoc.com.au>> wrote: David, I think that Stephen's original rant was not that this was one example of a page documentation needing improvement, but that the entire style of the documentation is so minimal as to be close to useless. Unless I'm getting to the wrong bits, very little of the documentation I reach initially on MSDN is of any more use than confirming syntactic correctness and the most minimal explanation of the usage variation. And as Stephen pointed out, sometimes almost laughably obvious explanations of usage at that. My recollections of earlier versions were that they contained much more descriptive information, examples, guidance on the use of methods and the like. As stated below, it starts to look like Google gives broader information than MSDN does. Cheers, Trevor From: ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com> [mailto:ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com>] On Behalf Of David Kean Sent: Thursday, 24 March 2011 2:17 AM To: djones...@gmail.com<mailto:djones...@gmail.com>; ozDotNet Subject: RE: Raising property changed events If you come across pages where you think the docs need improvement, please use the Rating box in the top right. Given that there's something like 200,000+ pages on MSDN, the UE (doc guys) combine that with page views to focus on low rated, high viewed pages first. From: ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com> [mailto:ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com>] On Behalf Of djones...@gmail.com<mailto:djones...@gmail.com> Sent: Wednesday, March 23, 2011 6:54 AM To: ozDotNet Subject: Re: Raising property changed events Imo. This has been the problem with msdn since the inception of .net. The last usable msdn was '98. Where you could find examples on all methods with related BUG: documents linked. The xml autodoc and java suffer from the same problem, the developers are there to write code and not provide examples. I haven't pressed F1 in visual studio since early 2001. It's a waste of time installing the docs as google will give you better and more concise information in half the time. .02c Davy "When all you have is a hammer, every problem looks like a nail." I feel much the same way about xml ________________________________ From: Stephen Price <step...@littlevoices.com<mailto:step...@littlevoices.com>> Sender: ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com> Date: Wed, 23 Mar 2011 21:48:10 +0800 To: ozDotNet<ozdotnet@ozdotnet.com<mailto:ozdotnet@ozdotnet.com>> ReplyTo: ozDotNet <ozdotnet@ozdotnet.com<mailto:ozdotnet@ozdotnet.com>> Subject: Re: Raising property changed events I was going to use this an opportunity to vent about the msdn documentation and then discovered that the page on this particular method is better than what I usually get on msdn docs. http://msdn.microsoft.com/en-us/library/system.reflection.assembly.getexecutingassembly.aspx Assembly.GetExecutingAssembly Method Gets the assembly that contains the code that is currently executing. <rant> so does anyone else get frustrated with this kind of documentation? It's like finding comments in your code that say "Gets the value from the property". yeah, I can see that from the code. Tell me something about why, or how to use it? 95% of the msdn doc pages have no examples. Typically, this particular one DOES but I'm sure thats because I wanted to rant about it and murphy's law was invoked. Most don't. Some explanations on what things actually do or why. Some examples. Please. We're guessing here and don't always have time or skills to crack open the dll with decompiler of the month and figure it out for ourselves. More examples please. Free standing, spelt out, working examples. Pretend we want to know how to use the methods. Give us an instruction manual. Please!! You'd make some happy people if you showed us how to use the framework. Throw some unit tests in there or something. </rant> thanks, Stephen On Wed, Mar 23, 2011 at 1:06 PM, David Kean <david.k...@microsoft.com<mailto:david.k...@microsoft.com>> wrote: Hmm, I'll check internally, but I'd be surprised if we give that guarantee. We're free to change our inlining policy at any time, in fact, we did just that in 3.5 SP1 x64 which broke a lot of customers who were relying on Assembly.GetExecutingAssembly() without explicitly turning off inlining for the method. Whether you can repro something now, is not a good indication of whether we'll continue to support in a future service pack or version - always check the docs. However, in saying that, the docs don't really make it clear that this might not work correctly in certain situations. In which case, if we don't give the above guarantee I'll make sure they call it out. -----Original Message----- From: ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com> [mailto:ozdotnet-boun...@ozdotnet.com<mailto:ozdotnet-boun...@ozdotnet.com>] On Behalf Of Mark Hurd Sent: Tuesday, March 22, 2011 9:36 PM To: ozDotNet Subject: Re: Raising property changed events On 23 March 2011 15:00, Mark Hurd <markeh...@gmail.com<mailto:markeh...@gmail.com>> wrote: > I believe it was in this mailing list that we previously confirmed > using GetCurrentMethod, even when included in convoluted ways, > guarantees the method will not be inlined. Gmail says GetCurrentMethod has /not/ been mentioned before on this mailing list since I've been part of it, so I'm remembering that wrong. > Can you show an example where GetCurrentMethod does not return the > expected method? This request still stands however. -- Regards, Mark Hurd, B.Sc.(Ma.)(Hons.)
