F***ing C#, F***ing Microsoft

[LeonBlade]

But seriously. You think that's terrible? Look at iOS/OSX documentation.

You got a point... :/
Nothing in the world of programming can ever be perfect after all...

Not sure what his experience with it is, or what specific part he is referring to, but the apple developer pages are very well done, and their documentation is extensive to say the least. And I know the MSDN pages can be "strange", but the are very very good.

http://developer.apple.com/library/mac/navigation/

Yeah, the Mac documentation is actually very good.

[EccentricDuck]

I think what's frustrating me is that it feels like, the more I try to teach myself through C#, the more I wind up teaching myself about using Microsoft's libraries as opposed to the thing itself. For example, I'm playing around with using XML for storing data so I need to figure out how C#/XNA deals with deserializing/serializing XML documents. I've been trying to get the same thing to work in Java too with the same XML document. I'm currently just playing around with making it work for 3 variables (something simple).

When I read stuff, I really want to find out how it works (even if it's just on a conceptual level and I use a library that does most of it anyway). When I look at doing it in Java, there's not a ton of official documentation, but I'm finding a lot of clear articles on different ways of doing it and how those would look (eg. I've been reading about SAX, DOM, and JAXB and I understand, more or less, what the first two are and how they differ). The thing I notice about what I come across for Java is that they normally try to explain how it's done (at least in what I've seen so far). By contrast, when I look at anything for C#/XNA, it just explains what calls to make in a particular namespace (or, you know, a dozen namespaces) and there are a ton of different ways of doing it. There's different ways of deserializing/serializing, in some cases it's first converted to another format, in some cases (in XNA) there's classes in the background that you never get to touch which act as reader/writer classes, whereas in other ways of doing it (including another XNA specific approach) you have to write those classes. I don't necessarily know what parts of the library I'm working with specifically, and when I try to find out I find that it's a big mish-mash of interconnected libraries and documentation. Most articles seem to be aimed at people who don't want to know what they're doing but just want it to work.

Microsoft DOES have an incredible amount of functionality in their libraries, and extensive documentation, but in a way I think that's part the issue. It's like having a legal system built upon layers and layers of legal precedent - it's unapproachable to someone who's either not familiar with a substantial portion of it's history and who isn't willing to go "copy + paste" (and then be dumbfounded when the opposition slaps them with some bit of obscure precedent they've never heard of). The history isn't necessarily a problem, but relying upon the fact that everyone who uses the system will have a knowledge of it's ever growing history and complexity is poor design.

Some number of months back, XianForce recommended a good set of XNA tutorials to me: http://rbwhitaker.wikidot.com/xna-tutorials
They don't cover everything, and I certainly ventured past them for more information, but they did do a good job of teaching you what you were doing with an overview of why you were doing it (gives you a place to go from if you want to learn more). It was very practical: you'd get one thing or another drawn to the screen and build on it, but it also told you enough about why you were doing it that you could understand why you were doing it.

That kind of simplicity and step-by-step approach is void from most of Microsoft's documentation as far as I can tell. Now I can understand why that approach won't work verbatim - Microsoft is, after all, trying to cater to as many different people trying to do as many different things with the same tool as possible. Add to that that they are trying to give documentation that allows people to implement these things immediately at a professional level (which is I think why C# is so popular - you have 1000s of professional "tools" at your disposable with documentation on each and every one of them). I think it really does an injustice though to not impart some wisdom about how or why the tool works - you know, a sort of big picture view. Tools are great, but they can be misused, and developing a reliance on a static way of doing things breeds ignorance and squashes problem solving. It's nice to be able to access a library that deserializes a document, converts it to another format, parses it for some tags, and let's you do more stuff with it; but what happens when an error arises and you have no idea why it happened because you never really understood the way the library was processing stuff in the first place?

I'm going to get it working in Java, and by the time I come back to C# I intend on having a better idea of what exactly is happening so that I'm not lost in a sea of "helpful" obscurity.

[EccentricDuck]

Reflecting on this, I think part of MY problem is that I want to learn so much, and C# seems directed at implementing a ton of functionality without necessarily imparting a deep knowledge of everything in there (because it's more efficient - no programmer can know everything, and I don't think many care to know). I'm asking for something that C# wasn't necessarily designed for and wondering why it's not there.

That being said, I do want to learn more because I want to become better, and I'm not satisfied with just using library implementations. Rather than blaming it on C# and Microsoft though, I think it's my responsibility to teach myself. I've had an opportunity open up to use some Python again (or Jython to be more accurate) in conjunction with Java, so I might use it to re-acquaint myself with some of the finer points that I didn't appreciate as much when I first started the language (typeless variables really are fast and incredibly easy to type).