Why does Microsoft (MSDN) documentation suck so much?
-
Indeed - given the choice between Borland, Oracle and Microsoft documentation, I always preferred MSDN.
*pre-emptive celebratory nipple tassle jiggle* - Sean Ewington
"Mind bleach! Send me mind bleach!" - Nagy Vilmos
CodeStash - Online Snippet Management | My blog | MoXAML PowerToys | Mole 2010 - debugging made easier
Given those choices, I'd go for gouging out your own eyeballs - get just as much information AND the pain's over quicker.
Panic, Chaos, Destruction. My work here is done. Drink. Get drunk. Fall over - P O'H OK, I will win to day or my name isn't Ethel Crudacre! - DD Ethel Crudacre I cannot live by bread alone. Bacon and ketchup are needed as well. - Trollslayer Have a bit more patience with newbies. Of course some of them act dumb - they're often *students*, for heaven's sake - Terry Pratchett
-
MSDN documentation is the worst documentation ever. Nothing is complete. The code examples are appalling, some are full programs with unrelated codes, some having to understand from with "...". And the coding convention is different every where. The most annoying part is completely wrong information, the other day I was looking at the LDAP API and MSDN said free the structure after use, which I did and it was crashing all the time, then I turned to the header file, it has more documentation than MSDN. And it said don't free this structure..WTF
Yes it has lots of warts. But it still has lots of information that is helpful. I held a very similar view to yours many years ago, but over time, I've come to recognize some of these warts and take what I read with a grain of salt. :)
Chris Meech I am Canadian. [heard in a local bar] In theory there is no difference between theory and practice. In practice there is. [Yogi Berra] posting about Crystal Reports here is like discussing gay marriage on a catholic church’s website.[Nishant Sivakumar]
-
MSDN documentation is the worst documentation ever. Nothing is complete. The code examples are appalling, some are full programs with unrelated codes, some having to understand from with "...". And the coding convention is different every where. The most annoying part is completely wrong information, the other day I was looking at the LDAP API and MSDN said free the structure after use, which I did and it was crashing all the time, then I turned to the header file, it has more documentation than MSDN. And it said don't free this structure..WTF
[ramble] It's like retirement benefits. They are affordable when the company is small and the company is going to make a lot of money before anyone retires. Then, the # of people getting the retirement pay starts to increase more than the growth / profit of the company, until retirement benefits starts to become a bigger burden on the company than the active employees. Maintaining documentation is like that too - the more a software company produces, the more the cost of keeping that documentation accurate and current. What we need is a wikipedia-style system where we can update the documentation ourselves - knowledge like what you figured out just vanishes a second later. If you don't use LDAP for the next 4 years and then have to do something again in it, chances are you yourself will have forgotten this gem of wisdom. Has happened often enough to me, both with 3rd party code and with my own code. But what would be really cool is if the IDE was really tied in to the documentation, so when you did a "free foo;" the environment would be smart enough to know that somewhere in the documentation was "do not free this structure." At the moment, we have a huge gap between information and how it's applied. Bridging that gap is what we are going to need tools for in the future. [/ramble] Marc
-
Yeah.. I'd say programmers/engineers as a whole tend to make crappy documentation. I think it's fair to say no one is thrilled to make the stuff... X|
-
Yeah.. I'd say programmers/engineers as a whole tend to make crappy documentation. I think it's fair to say no one is thrilled to make the stuff... X|
Albert Holguin wrote:
I'd say programmers/engineers as a whole tend to make crappy documentation
Can you point out the crappy piece for me? As far as I can see, it's structured in a predictable way. The texts are clear, the exceptions all named an explained. Even code-examples in each .NET language, for each version of the .NET language. As a user, I can add annotations, and there's a huge amount of walkthroughs and howto's that walk you through a task step by step. It is NOT a learning-book, that I agree. That's why we call it "documentation". Try creating an MSI-like installer for Ubuntu, and we'll talk again :)
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
-
[ramble] It's like retirement benefits. They are affordable when the company is small and the company is going to make a lot of money before anyone retires. Then, the # of people getting the retirement pay starts to increase more than the growth / profit of the company, until retirement benefits starts to become a bigger burden on the company than the active employees. Maintaining documentation is like that too - the more a software company produces, the more the cost of keeping that documentation accurate and current. What we need is a wikipedia-style system where we can update the documentation ourselves - knowledge like what you figured out just vanishes a second later. If you don't use LDAP for the next 4 years and then have to do something again in it, chances are you yourself will have forgotten this gem of wisdom. Has happened often enough to me, both with 3rd party code and with my own code. But what would be really cool is if the IDE was really tied in to the documentation, so when you did a "free foo;" the environment would be smart enough to know that somewhere in the documentation was "do not free this structure." At the moment, we have a huge gap between information and how it's applied. Bridging that gap is what we are going to need tools for in the future. [/ramble] Marc
Marc Clifton wrote:
But what would be really cool is if the IDE was really tied in to the documentation
XML Documentation. ..which doesn't mean that you could not come up with a better alternative. Write a plugin for VS and an article for CP, we'd all benefit.
Marc Clifton wrote:
At the moment, we have a huge gap between information and how it's applied. Bridging that gap is what we are going to need tools for in the future.
I disagree. The info is all there, but it cannot be applied in a JIT-manner. The problem here is rather "education".
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
-
[ramble] It's like retirement benefits. They are affordable when the company is small and the company is going to make a lot of money before anyone retires. Then, the # of people getting the retirement pay starts to increase more than the growth / profit of the company, until retirement benefits starts to become a bigger burden on the company than the active employees. Maintaining documentation is like that too - the more a software company produces, the more the cost of keeping that documentation accurate and current. What we need is a wikipedia-style system where we can update the documentation ourselves - knowledge like what you figured out just vanishes a second later. If you don't use LDAP for the next 4 years and then have to do something again in it, chances are you yourself will have forgotten this gem of wisdom. Has happened often enough to me, both with 3rd party code and with my own code. But what would be really cool is if the IDE was really tied in to the documentation, so when you did a "free foo;" the environment would be smart enough to know that somewhere in the documentation was "do not free this structure." At the moment, we have a huge gap between information and how it's applied. Bridging that gap is what we are going to need tools for in the future. [/ramble] Marc
For some reason, my mind goes to Code Contracts[^]. It'd be like taking Code Contracts and iterating them to the next level.
-
MSDN documentation is the worst documentation ever. Nothing is complete. The code examples are appalling, some are full programs with unrelated codes, some having to understand from with "...". And the coding convention is different every where. The most annoying part is completely wrong information, the other day I was looking at the LDAP API and MSDN said free the structure after use, which I did and it was crashing all the time, then I turned to the header file, it has more documentation than MSDN. And it said don't free this structure..WTF
I think that's a bit unfair. I use MSDN on an almost daily basis and it has improved greatly in the last 5 years. It's clearer and easier to find stuff than before. Consider yourself lucky, you could be reliant on http://www.php.net/[^] for your documentation.
-
Albert Holguin wrote:
I'd say programmers/engineers as a whole tend to make crappy documentation
Can you point out the crappy piece for me? As far as I can see, it's structured in a predictable way. The texts are clear, the exceptions all named an explained. Even code-examples in each .NET language, for each version of the .NET language. As a user, I can add annotations, and there's a huge amount of walkthroughs and howto's that walk you through a task step by step. It is NOT a learning-book, that I agree. That's why we call it "documentation". Try creating an MSI-like installer for Ubuntu, and we'll talk again :)
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
I know programmers hate documenting, but being a big company with lots of money, they can afford some good documentation guys/gals that keep them up to date based on the developer's incoherent documentation. In this ldap case why is there more documentation in the header file.
-
I know programmers hate documenting, but being a big company with lots of money, they can afford some good documentation guys/gals that keep them up to date based on the developer's incoherent documentation. In this ldap case why is there more documentation in the header file.
ktm TechMan wrote:
I know programmers hate documenting
That's a nice generalization, but if you browse the articles here you get quite a different impression.
ktm TechMan wrote:
but being a big company with lots of money, they can afford some good documentation guys/gals that keep them up to date based on the developer's incoherent documentation.
Being a big company, I am surprised by their level of consistency in the quality and structure of the documentation. I do not know what you "expect" to find there, but it's as good and complete a reference as the MSDOS 5.0 Reference Manual. Yes, there will be some abominations in there. You can't have that much documentation without some crap somewhere. That still does not make the entire library "crap". On the contrary, it is one of the better examples out there. Enjoy the DevExpress documentation, if you didn't find the Linux-proposal interesting.
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
-
Albert Holguin wrote:
I'd say programmers/engineers as a whole tend to make crappy documentation
Can you point out the crappy piece for me? As far as I can see, it's structured in a predictable way. The texts are clear, the exceptions all named an explained. Even code-examples in each .NET language, for each version of the .NET language. As a user, I can add annotations, and there's a huge amount of walkthroughs and howto's that walk you through a task step by step. It is NOT a learning-book, that I agree. That's why we call it "documentation". Try creating an MSI-like installer for Ubuntu, and we'll talk again :)
Bastard Programmer from Hell :suss: if you can't read my code, try converting it here[^]
Eddy Vluggen wrote:
Can you point out the crappy piece for me?
If I have an open connection on a Socket then what does Dispose do - based on the documentation? Again per the documentation - what happens for BeginReceive if the socket is closed (a normal socket close) by the server before it is called? http://msdn.microsoft.com/en-us/library/system.net.sockets.socket.aspx[^] One can define behavior, protocol, etc for WCF via XML (other other ways too.) Where is the documentation that delinates in a useful way the difference in configuration for the server side versus client side set ups. There are differences by the way. For WCF net.tcp protocol what is the difference between a connection failure and a response failure? In terms of server processing those represent very different process failures. Where is the documentation for MS Access SQL? Not MS Access itself but rather the description of the SQL that one can use in creating appropriate constructs in it. I should note that I don't find the MS docs to be particularily bad. But they are not great either.
-
MSDN documentation is the worst documentation ever. Nothing is complete. The code examples are appalling, some are full programs with unrelated codes, some having to understand from with "...". And the coding convention is different every where. The most annoying part is completely wrong information, the other day I was looking at the LDAP API and MSDN said free the structure after use, which I did and it was crashing all the time, then I turned to the header file, it has more documentation than MSDN. And it said don't free this structure..WTF
google
".45 ACP - because shooting twice is just silly" - JSOP, 2010
-----
You can never have too much ammo - unless you're swimming, or on fire. - JSOP, 2010
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass." - Dale Earnhardt, 1997