Why does Microsoft (MSDN) documentation suck so much?
-
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