Is MSDN deteriorating?
-
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighist -
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistI think a lot of the GDI & GDI+ stuff is poorly documented. That said, yeah, overall I think there's lots of room from improvement over at MSDN. CP frequenter (and great CP article writer) Wesner Moise touched[^] on this recently.
Tech, life, family, faith: Give me a visit. I'm currently blogging about: Bought a House! Judah Himango
-- modified at 10:21 Wednesday 28th December, 2005
-
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighisttotally agree with you here....Microsoft documentation has been going steadily downhill in recent years. Take a look at their Uniscribe documentation: http://msdn.microsoft.com/library/en-us/intl/uniscrib_44f9.asp[^] Compare this to the ATSUI documentation from Apple which covers their own related technology: http://developer.apple.com/documentation/Carbon/Conceptual/ATSUI_Concepts/[^] The Apple docs are clear, easy to read, have good diagrams. The Microsoft docs are utterley incomprehensible and in places are actually *wrong* Are Microsoft deliberately writing bad docs to open up the market for their book publishing departments or have they just lost their way? come on MS buck your ideas up! james
http://www.catch22.net -
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistMSDN has been going downhill since the rise of the Internet. Back in the day, The budget wouldn't stretch for books so the MSDN cds were my only way of learning about an API or class library. Since the Internet has become mainstream, I usually hit CP or Google if I want a code-sample. MSDN has been relegated to F1 for help when I can't remember a syntax and intellisense is playing up. I used to love MSDN. I'd spend hours reading all the articles on the library CD's when the new shipment arrived. I miss the days of Nancy Clutz and her ilk, those people knew how to write for their audience. Now though, too many articles concentrate on the latest and greatest. If I want to read up on a subject that is more relevant, google usually finds me a good article that has been written by somebody who has actually used the API in anger and not written the sample as part of their job description. I'm glad to see people like Tom Archer being recruited by MSDN, people with real world experience who know what we need. Michael CP Blog [^] Development Blog [^]
-
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistThis document is lot better than the symbian documentation (sometimes no documentation, I have to lookup in the header file to understand what the APIs might do) that I was working on rite now. Yes may be it not that properly documented (according to you) but I found it ok (or better than before when they listed only the Apis). The documentation of Windows SDK has proved to be very usefull to novice.
-Prakash
-
This document is lot better than the symbian documentation (sometimes no documentation, I have to lookup in the header file to understand what the APIs might do) that I was working on rite now. Yes may be it not that properly documented (according to you) but I found it ok (or better than before when they listed only the Apis). The documentation of Windows SDK has proved to be very usefull to novice.
-Prakash
Mr.Prakash wrote:
This document
Which? The one I linked to was my example for good documentation. GDI+ simply lacks an equivalent (even though pixel positioning definitely got more complex). I find this a lot in MSDN, few topics are documented well, but digging deeper we end up with "autodocumented source code".
Mr.Prakash wrote:
The documentation of Windows SDK has proved to be very usefull to novice.
Absolutely. I simply loved it both as beginner and "seasoned user". But for .NET, it's almost useless.
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighist -
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistWhat Microsoft should do, is make a WIKI out of the MSDN On-line so the community can keep it properly updated.
:..::. Douglas H. Troy ::..
Fold with us|Development Blogging|viksoe.dk's site -
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistWho can find why this event[^] isn't being raised, and when it should be raised. You won't find it easily. At least, I could only find it by using Reflector. I reported it on 11/16/2005 to MSDN documentation feedback and what to change in the docs. Their answer: "Hi Daniel, Excellent point! I've filed a bug to update the Exited event documentation. Thanks for pointing this out, Shel Blauman .NET Framework UE" As of today, almost 45 days later, nothing changed. I don't believe that I'm the only one sending this feedback. It seems that people at MSDN are simply too slow at changing the documentation, so they are not able to keep up with suggestions, corrections and new documentation for new APIs. From the Churchdown Parish Magazine: "Would the Congregation please note that the bowl at the back of the Church, labelled 'For The Sick,' is for monetary donations only."
-
Who can find why this event[^] isn't being raised, and when it should be raised. You won't find it easily. At least, I could only find it by using Reflector. I reported it on 11/16/2005 to MSDN documentation feedback and what to change in the docs. Their answer: "Hi Daniel, Excellent point! I've filed a bug to update the Exited event documentation. Thanks for pointing this out, Shel Blauman .NET Framework UE" As of today, almost 45 days later, nothing changed. I don't believe that I'm the only one sending this feedback. It seems that people at MSDN are simply too slow at changing the documentation, so they are not able to keep up with suggestions, corrections and new documentation for new APIs. From the Churchdown Parish Magazine: "Would the Congregation please note that the bowl at the back of the Church, labelled 'For The Sick,' is for monetary donations only."
... this is a good reason why making the MSDN a WIKI would allow for faster "turn around" for these kinds of issues ... You could have made the change, and the community would keep the doc's on the straight and narrow; with MS employees ultimately checking everything over and improving upon what's there (if need be).
:..::. Douglas H. Troy ::..
Fold with us|Development Blogging|viksoe.dk's site -
What Microsoft should do, is make a WIKI out of the MSDN On-line so the community can keep it properly updated.
:..::. Douglas H. Troy ::..
Fold with us|Development Blogging|viksoe.dk's siteDouglas Troy wrote:
What Microsoft should do, is make a WIKI out of the MSDN On-line so the community can keep it properly updated.
My initial reaction was, wow, what a great idea, why wait for Microsoft to do that? But it occurs to me that you'd want to at least start with the MSDN content, which is of course copyrighted. So yes, I guess Microsoft would have to take the lead. Marc Pensieve
-
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistI used to complain about MSDN, especially the built-in search or the browser software, but now I don't anymore. University forced me in using Java, and I scream and suffer every time I need to open the javadoc. It is really much, much, much, much, much, worse than MSDN. I would pay to get a better, simpler, birds-eye documentation. It is really difficult to understand how things have to be done with a mere reference. Luca The Price of Freedom is Eternal Vigilance.
-
Douglas Troy wrote:
What Microsoft should do, is make a WIKI out of the MSDN On-line so the community can keep it properly updated.
My initial reaction was, wow, what a great idea, why wait for Microsoft to do that? But it occurs to me that you'd want to at least start with the MSDN content, which is of course copyrighted. So yes, I guess Microsoft would have to take the lead. Marc Pensieve
Marc Clifton wrote:
My initial reaction was, wow, what a great idea
Well, this was my one "great idea" for 2005. About time I came up with something. :->
Marc Clifton wrote:
guess Microsoft would have to take the lead.
Yes, yes they would.
:..::. Douglas H. Troy ::..
Fold with us|Development Blogging|viksoe.dk's site -
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistThere's no doubt about it in my mind. The documentation for the new stuff (.NET, GDI+ etc) is definitely not up to the standard MS has set in the past. Mind you, the .NET documentation is like a good reference book by comparison with the documentation on Visual Studio extensibility (especially the automation interfaces for indicidual language services such as Visual C++ *). Now that is truly crap documentation!!! :| * I spent most of yesterday trying to figure out how to retrieve a VS2005
VCProjectEngineLibrary::VCPlatforminterface when no solution/project was opened so we could get our include folder config reading code working in VS2005, which has a different interface from VS2002/2003 in this area. When we finally cracked it we found the interface returns incomplete results, so that was a waste of time. Samples? What Samples? :mad: Anna :rose: Currently working mostly on: Visual Lint :cool: Anna's Place | Tears and Laughter "Be yourself - not what others think you should be" - Marcia Graesch "Anna's just a sexy-looking lesbian tart" - A friend, trying to wind me up. It didn't work. -
What Microsoft should do, is make a WIKI out of the MSDN On-line so the community can keep it properly updated.
:..::. Douglas H. Troy ::..
Fold with us|Development Blogging|viksoe.dk's siteI've been a fan of that idea, ever since i first saw documentation like this, where notes can be appended. Or even think how much of an improvement it would be, if all MSDN pages suddenly had CodeProject-style article forums!
---- Scripts i've known... CPhog 0.9.9 - make CP better. Forum Bookmark 0.2.1 - bookmark forum posts on Pensieve Print forum 0.1.2 - printer-friendly forums
-
I've been a fan of that idea, ever since i first saw documentation like this, where notes can be appended. Or even think how much of an improvement it would be, if all MSDN pages suddenly had CodeProject-style article forums!
---- Scripts i've known... CPhog 0.9.9 - make CP better. Forum Bookmark 0.2.1 - bookmark forum posts on Pensieve Print forum 0.1.2 - printer-friendly forums
Shog9 wrote:
where notes can be appended. Or even think how much of an improvement it would be, if all MSDN pages suddenly had CodeProject-style article forums!
Now that would make the MSDN hugely power full!
ZeePain! wrote:
This seems like one of those programs that started small, grew incrementally, building internal pressure, and finally barfed all over its source code sneakers. Or something.
-
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistI think the decline in quality of MSDN documentation can be traced directly to the metastasis of API's since the advent of .NET. We've had three major revisions of the framework in that time. I'm sure documentation is a low priority at Microsoft, like any other company under pressure to create product and get it out the door. Microsoft has one advantage, however. They don't have to document everything. They realize that, if an API is documented poorly, some poor slob will figure it out and write an article for Code Project.
Software Zen:
delete this; // [Fold With Us!](http://www.codeproject.com/script/profile/whos_who.asp?msg=1307432&id=10338#xx1307432xx)[[^](http://www.codeproject.com/script/profile/whos_who.asp?msg=1307432&id=10338#xx1307432xx "New Window")] -
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistYes, agreed on both getting old and quality detoriation of MSDN. Actually I am gong back to (call me whatever you whish) good old C and Basta!, nothing has really changed, the costs of upgrading has become too high with respect to the gains made. Yes, industry and business 'demands' it but that is their problem and theirs alone. Yes, I think I am getting older and hopefully a little wiser too.
-
I'm using some free time to dabble with C#/.NET. What irks me most is that MSDN isn't as helpful as it used to be. Maybe I'm just getting old, but these are my observations: (1) Blob of information the "old" MSDN offered for small sections like "Clipboard" or "GDI Lines and Curves" always three parts: 1. "About X" with general information and design philosophy 2. "Using X", coding and explaining common tasks 3. "X Reference" with, well, a reference. "About X" seems to have vanished completely, "Using X" is replaced by plain, often uncommented code samples spread over the actual reference, leaving us with huge lists of namespaces, classes, methods and properties. Example: - About Lines in GDI documentation[^] - About Lines in GDI+ documentation (wonder why there's no clickety?) (2) Automatic Garbage Most Member descriptions just have a generic description ("Draws a line connecting the two points specified by coordinate pairs") with TONS of boilerplate I understand that documenting the .NET framework is an immense task. Still, MSDN was IMO the biggest selling point of windows development. Heck, I learnt MFC development using MSDN. What is your opinion? Are you getting along with MSDN better, or worse than in the "good old days"? Maybe I'm just getting old..
We say "get a life" to each other, disappointed or jokingly. What we forget, though, is that this is possibly the most destructive advice you can give to a geek.
boost your code || Fold With Us! || sighistI have programmed for quite some different things, like a lot of TAPI where I had to read different vendors documentation about what they supported, Dialogic Boards, strange USB encryption keys and stuff like that... Let me tell you, the best documentation I have ever seen is MSDN! - Anders