Thanks David. I feel much happier about my rant now. I don't usually do them, but really happy to know that it's not fallen on deaf ears. Passing it up the chain is the best thing I could hope for, short of the documentation actually being improved. :) On Thu, Mar 24, 2011 at 11:28 AM, David Kean <david.k...@microsoft.com>wrote:
> 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> > 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] *On Behalf Of *David Kean > *Sent:* Thursday, 24 March 2011 2:17 AM > *To:* 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] *On Behalf Of *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> > > *Sender: *ozdotnet-boun...@ozdotnet.com > > *Date: *Wed, 23 Mar 2011 21:48:10 +0800 > > *To: *ozDotNet<ozdotnet@ozdotnet.com> > > *ReplyTo: *ozDotNet <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> > 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] > 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> 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.) > > > > >
