Real Programmers

[dbasnett]

A discussion, in another thread, following a solution began here;
"But there is also such a thing as 'too much information'. People don't care how the function is declared, or how it's used in a class, a simple one-line example, along with the input and output of the function is perfectly enough in most cases.

Would you rather read a 200-page users manual that explains everything, from what platform the program was developed on and how, to how the code is written, did they write with both hands or not, just to find out how to use a 2MB utility? Or would you rather read a 2-page concise tutorial that brings you up to speed on everything you need to know in 30 seconds?"

What do you think?

[Jenner]

(Thanks for the move)

The point is simply MSDN is a cluttered mess of useless information. The layout is atrocious. An example using the String.Insert page on MSDN:




Problems with the page? Too much garbage! Why do we need that tree on the side? It should be collapsed. What's with all the headings? Get rid of them. I'm programming in Visual Basic, I shouldn't have to deal with a complex language filter system, I should just be taken to a page on Visual Basic. Finally, put the most important information at the top of the page. Include a quick example showing it's use.

Here's a mock-up of a much cleaner, far easier to read version of this page:

[timeshifter]

Simple question. How does MSDN know you're using VB? I use C#. EVERY SINGLE USER will have that same issue, and it's unavoidable because there are different languages. And that tree is there to provide quick access to related information. If you don't like it, frankly it's your problem. I don't like it either, but I live with it because it tells me what I need to know.

[obi1kenobi]

I would also put the Remarks part before the Exceptions part, since, personally, I'm much more interested in what the arguments are used for, than what exceptions can occur. I imagine most beginner-to-intermediate programmers would agree with me

[obi1kenobi]

Why not take Yahoo!'s approach? Give users an option to log in and make whatever customizations they want, including layout, amount of info and programming languages?

[timeshifter]

VB in itself is a bad language. Not bad in the sense of being inferior (which it also is), but bad in the sense of it's too verbose. Yes, it's painfully easy to code in. Type what you want to do, and it's probably a real command. But it loses lots of meaning with that verbosity, ironic as it may seem. "Nothing", for example. Nothing could easily mean an integer of 0, a zero-length string, or a null value. Would it have been too much to ask to just use null the way most other languages do? Hell, even SQL uses null.

[dbasnett]

Funny you should say that ob1. Who cares what can go wrong. And when it does just go to vbforums and whine about it till someone that has read more than you points out what was documented in the first place.

Jenner, please go to MSDN and make your case and let me(us) know where the thread is. I will support it for sure.

[space_monkey]

Having the other languages side by side can be very helpful if you have a basic understanding of them.

[Atheist]

Jenner:
Basically what you want is for the left hand tree to go away, and the links at the top of the page that tells you where you are on the site?
IMO you cant just remove these features. The links on the top of the document are really great:
MSDN > MSDN Library > .NET development > .NET Framework 3.5 > etc > etc
It helps you to know where you are on the HUGE site, and also helps you to go backwards in the site structure.

The same thing really goes for the tree. Its a way of navigating around the site. I dont see a simple way of navigation on your "mock-up" picture.

Saying that MSDN is a cluttered mess of useless information is, in my opinion, ignorant. MSDN contains a HUGE amount of information, and code examples for many different languages. Where is the useless information?

[Jenner]

Simple question. How does MSDN know you're using VB?

Because the page and/or the search would see your browser has no cookie set for the language and ask you up-front. It doesn't though, and the unknowing has to "discover" the language filter but not before becoming confused and overwhelmed first.

@Athiest:

No, not just go away, just hide them or collapse them by default. Cut right to the relevant information. Yea, after looking at my mockup, I do like the top-links, though those could be cut down. Maybe the last-three steps in or so, or better yet, scale it with the client area .

[obi1kenobi]

Funny you should say that ob1. Who cares what can go wrong. And when it does just go to vbforums and whine about it till someone that has read more than you points out what was documented in the first place.

Well, in my experience, most errors occur because there is something wrong with the arguments, so if their explanations were a bit higher on the page, perhaps more ppl would see them, preventing errors from occuring. Personally, I don't care what kind of errors might occur until they occur. But that's me

[timeshifter]

Because the page and/or the search would see your browser has no cookie set for the language and ask you up-front. It doesn't though, and the unknowing has to "discover" the language filter but not before becoming confused and overwhelmed first.

Which is why the filter is at the top of the page. Easy to see, clearly defined. You're whining for no reason.

[dbasnett]

You mean errors like this

        Dim abc As String = "abc"
        abc.Insert(5, "XYZ")

The explanation of why this is wrong is high on the page, it is called Exceptions.

Is this whole topic about formatting of MSDN?

[dbasnett]

I see many cases where (Usage) could be more (Useful), for example

Dim instance As String
Dim startIndex As Integer
Dim value As String
Dim returnValue As String

returnValue = instance.Insert(startIndex, _
    value)

'could be

Dim instance As String = "ABCD"
Dim startIndex As Integer = 2
Dim value As String = "I"
Dim returnValue As String

returnValue = instance.Insert(startIndex, _
    value) 'ABICD

[obi1kenobi]

You mean errors like this

        Dim abc As String = "abc"
        abc.Insert(5, "XYZ")

The explanation of why this is wrong is high on the page, it is called Exceptions.

Is this whole topic about formatting of MSDN?

Oh come on! The only person that couldn't figure out what's wrong with the code is either a complete beginner, in which case he would read the entire page and not only the first two lines, or has IDIOT written on his forehead.

[timeshifter]

You haven't been here very long... you clearly don't know the types of people that try to program.

[Jenner]

Which is why the filter is at the top of the page. Easy to see, clearly defined. You're whining for no reason.

No, because I know it took me about 2 months to take notice of it; and did it prompt me? No, it didn't.

Now imagine you buy a manual for a garage door opener, and in the instructions to set it's dip switches to your garage door, every paragraph was in a different language and it cycled through them, so maybe English was every 7th paragraph...

I've read manuals like that and I think the universally accepted opinion of them are: They outright suck.

What's the alternative? Well, have 7 different manuals in the box with the garage door opener, one for each language. Why don't companies do that? Because paper and printing costs money.

But web pages are free! FREE!! And not having all the other languages on the same page by default, prompting the user UP FRONT like he was picking one of seven manuals out of a box, makes life easier for everyone and cuts down bandwidth as well.

[timeshifter]

You not noticing something that's hidden in plain site for two months is your own damned fault. Hate to break it to ya, but I noticed it the first time I used it. Why? Because there were C++ examples and I was looking for VB. So I poked around and found the filter.

Manuals generally do come in multiple languages because it's not a guarantee that the buyer will speak english. Sometimes it's a separate manual, sometimes it's appended to the end of the English section. It's there so EVERYBODY can use the product, not just you.

And for those of us that are proficient in more than one language? It's NICE to see how other languages do it. Comparison. You can rank languages against each other very easily.

Now stop crying, go ask mommy to tuck you in for a nap and some hot milk, and realize that there are other people that use MSDN besides you. And I'm not talking just a few... I mean probably thousands at any given time. MSDN is designed to make life the same for everybody, which you have to agree is only fair.

[Bopo]

*Fire extinguisher*

[Jenner]

And if making the life the same for everyone is the wrong approach?

(Yea, no kidding Bopo... I hate arguing with people who start getting vicious because an objective approach to their little universe threatens to pop their little bubble. )

[penagate]

Jenner, have you tried offline MSDN?

[penagate]

You not noticing something that's hidden in plain site for two months is your own damned fault. Hate to break it to ya, but I noticed it the first time I used it. Why? Because there were C++ examples and I was looking for VB. So I poked around and found the filter.

Manuals generally do come in multiple languages because it's not a guarantee that the buyer will speak english. Sometimes it's a separate manual, sometimes it's appended to the end of the English section. It's there so EVERYBODY can use the product, not just you.

And for those of us that are proficient in more than one language? It's NICE to see how other languages do it. Comparison. You can rank languages against each other very easily.

Now stop crying, go ask mommy to tuck you in for a nap and some hot milk, and realize that there are other people that use MSDN besides you. And I'm not talking just a few... I mean probably thousands at any given time. MSDN is designed to make life the same for everybody, which you have to agree is only fair.

Play nice or it's a trip to the naughty corner.

[techgnome]

Because the page and/or the search would see your browser has no cookie set for the language and ask you up-front. It doesn't though, and the unknowing has to "discover" the language filter but not before becoming confused and overwhelmed first.

@Athiest:

No, not just go away, just hide them or collapse them by default. Cut right to the relevant information. Yea, after looking at my mockup, I do like the top-links, though those could be cut down. Maybe the last-three steps in or so, or better yet, scale it with the client area .

Hey Jenner.... see those four dots in the splitter bar? Double click it... makes the tree go away.
As for some of the convoluted data, one man's junk is another man's treasure trove. I find some of that implementation stuff useful. Most times the example is junk, especially the VB ones, so I rely on the C# examples to help me.

Jsut to let you know b!tcvhing about it here isn't going to do any good except make people defensive (me included) about the subject. Heck, MSDN is WAAAAY better than it was 5 years ago. Stop complaining. Want to do some good? Then use the frigging feedback option in MSDN. That's what it's for.

-tg

[mendhak]

Jenner - you can move the 'treeview' frame; resize it and move it to the left, and I think you can double click it too and it will collapse.

Also, you should be able to specify a filter at the top of the content page (main frame).

[dbasnett]

I notice this for examples more and more

Console.WriteLine("The original string is:{0}{1}{0}", Environment.NewLine, strTarget)

Why not Debug.WriteLine?

[dbasnett]

Real programmers are into minutiae.

[Jenner]

@tg - I actually tried to use the feedback on that page and after 10 minutes of typing my opinion of it and rating it, I hit "submit" and I got shot to a page "We could not complete your request". Hitting back lost the data.

@mendhak, penagate
Oh, I know I can. And I have. Personally, I have little trouble navigating MSDN's site or getting info from it anymore. jmc convinced me to give it another go and I did, and I'm happy to say I understand the site a lot better now.

My argument is primarily one of: Can it be simpler? Can it be easier? I hated MSDN with a passion when I started moving from VB6 to VB.NET a couple years ago. Back then, you were lucky as hell to find ANY example code in the whole library. I was used to the MSDN library of VB6 where every function had a chunk of example code.

So I stopped using it. I found it frustrating and hard to get the info I needed from it. Typing "String.Insert VB.NET" into Google brought MSDN as the first hit, and an offsite that always seemed to explain what I wanted to know in about 3 sentences or a very short code sample. When I switched to VB2005, I started using it again and once again got frustrated at it.

After an older argument with jmc on here, he convinced me to try it again; third time was a charm and I understand it much better now. I see they've added a LOT of examples (maybe not the best examples to get the point across, but examples nonetheless.)

But it took me 3 tries. And post after post after post on here, I see people saying "I don't understand the help!", and it reminds me of my frustrations. To a new programmer, MSDN seems to universally suck. It has a learning curve. I don't see why it needs a learning curve!

One person reads a page and his eyes glaze over at the enormous amount of crud filling his browser window, of which he hardly understands any of it. All he want to know is how to use what he searched for. He shouldn't have to sit there and sift through the text to find it! He posts back "The help isn't that helpful". I post four bloody lines of code, and he INSTANTLY understands it! THAT to me, as a programmer, as an educator, and even as an amateur web developer "There is a serious problem here with getting information across".

Surely there has to be a better way to present this information to all levels of users? Timeshifter argued about the language filter and you mendhak, mention the treeview movable. That's great once you figure out how to use the web page, but a web page shouldn't be like learning to use a new software application; especially to a new user heading there looking for answers. Instead of a clear answer, he gets assaulted with mounds of seemingly pointless data. It should be the other way around... A new user should get a minimalist page with the option to add to it. It's a simple website trick to prompt for a programming language up front... so... why doesn't it? Other programming sites do or have some segregation of languages. THIS site does... you have a separate forum for VB.NET and C# after all.

Maybe I'm wrong, maybe the MSDN library in it's current incarnation is exactly what's needed for 95% of the users out there. Heck, I'm betting it is. Those people mostly don't post here because they get their knowledge from MSDN's library just fine.

But if you rule out the kids who download Xpress with the thought "I'm gonna be a programmer!!" and figure posting is faster than reading a friggin book, or the kids posting their completely unsolved homework problems on here because they're lazy and don't want to learn it or even the occasional expert who gets totally stumped by some advanced concept... there's a lot of people on here who have already tried MSDN for help and still can't grasp some fairly simple concept.

Why is that? That's my question. They can't ALL be morons? Some are posting code examples showing complex business apps. I dunno. I'm kinda argued out on this topic.

[obi1kenobi]

Yeah, one more thing is wrong with dbasnett's example:

I've never ever used the console to print out info and I've never gotten that part with {0} and {1}. What the hell are they and why are they used in a basic example?

[timeshifter]

Jenner:
About MSDN being more like an application than a "normal" website... that's EXACTLY what it is. Open Visual Studio, and you have the option of creating Web Applications. This is exactly their purpose. While "web sites" are designed to convey information and some even allow for feedback, a web application is designed for so much more. Data communications, client-server communication, all designed for the purpose of interactivity. Welcome to Web 2.0


And pena... don't kill me for that last comment...

[techgnome]

Jenner:
About MSDN being more like an application than a "normal" website... that's EXACTLY what it is. Open Visual Studio, and you have the option of creating Web Applications. This is exactly their purpose. While "web sites" are designed to convey information and some even allow for feedback, a web application is designed for so much more. Data communications, client-server communication, all designed for the purpose of interactivity. Welcome to Web 2.0


And pena... don't kill me for that last comment...

I'm waiting for 3.0 ... things never really work until version 3.0 ... I forget the name of the "law"....

@jenner - well bully for you then. Write your own MSDN website and point people to it. Then maintain it... And keep it up to date... And make sure that it's coherent enough so that EVERYone will understand... And make sure that it doesn't talk down to people either... And make sure there's plenty of REAL WORLD examples that makese the most amount of sense w/o using a bunch other other stuff that would need to be looked up.... And make sure it's easy to navigate. Make sure it's navigatable at all.

-tg

-tg

[Jenner]

Trust me TG, I've given it some serious thought about a year back. Registering a domain, linking to varieties of code examples, yadda yadda... and if I had the time to invest in that kind of project, I really think I would.

Maybe when I retire.

I don't care too much for the whole Web2.0 concept. I'm with you TG, I'm waiting for 3.0. Some "Web2.0" applications are nice, but I think most are overboard. Cripes, look at the mess of MySpace. I get asked at least once a week what my MySpace page is. I laugh and walk away. God, I dread having to go there to find anything.

Maybe I'm just disenchanted with the direction the web is going. It's taking steps backwards, and I pray to whatever god will listen that it's for the purpose of taking more steps forward. Maybe it comes from remembering the days I typed my archie searches after a VMS prompt or shelling out $400 for my first 300 baud modem. But that's a completely different discussion.

[dbasnett]

Yeah, one more thing is wrong with dbasnett's example:

I've never ever used the console to print out info and I've never gotten that part with {0} and {1}. What the hell are they and why are they used in a basic example?

1. Please read my post carefully.
2. Why don't you know about {}? hint is here, but you have to read
http://msdn2.microsoft.com/en-us/library/ms172582.aspx

You know I am not picking on you, I hope.

[MaximilianMayrhofer]

I'm waiting for 3.0 ... things never really work until version 3.0 ... I forget the name of the "law"....

I believe the law is: "Third time's the charm."

[CodedFire]

Actually i have a half written document on how to use the MSDN website!! Ive showed it to Robdogg888 and JMC, il finish it at by next week ( i forgot about it) and post it in the tutorial bank, its actually quite handy when you get the hang of it.

[obi1kenobi]

1. Please read my post carefully.
2. Why don't you know about {}? hint is here, but you have to read
http://msdn2.microsoft.com/en-us/library/ms172582.aspx

You know I am not picking on you, I hope.

Yeah, I know, don't worry...

I know the use of {} when declaring arrays, but what the hell is it doing in the middle of the Console.WriteLine? Surely it's not representing an Integer array with a single value of 0 or 1?

[dbasnett]

Console.WriteLine("The original string is:{0}{1}{0}", "zero", "one")

produces

The original string is:zeroonezero

does that help

Why they use Console.WriteLine("The original string is:{0}{1}{0}", "zero", "one")
instead of Debug.WriteLine("The original string is:{0}{1}{0}", "zero", "one")

is beyond me.

[Atheist]

Yeah, I know, don't worry...

I know the use of {} when declaring arrays, but what the hell is it doing in the middle of the Console.WriteLine? Surely it's not representing an Integer array with a single value of 0 or 1?

Well, if we really must discuss technical stuff in the wrong forum...
Thats a common way to format output. Its used in a variety of forms in most languages.

string YourName = "obi1kenobi"
string MyName = "Atheist";
Console.WriteLine("Hello {0}, my name is {1}", YourName, MyName);

For example, in C you'd do this:

char* YourName = "obi1kenobi";
    char* MyName = "Atheist";
    printf( "Hello %s, my name is %s", YourName, MyName );

Very practical.

[techgnome]

place holders.... they are place holders... they allow different parameters to be insterted in spots...

I have an aexampleat home on how to use it to construct connectionstrings, I'll try to post it later tonight.

-tg

[kleinma]

Medhak got it right in his post above..

just double click the resize bar of the treeview and it will collapse. This makes more room for the documentation, and also makes pages load faster on MSDN docs.

It was also mentioned that you can filter out language examples you don't want to see, and you can click "Collapse All" if there is too much info on the page for you, and you want to drill down to the specific area you want.

I have no problems using the MSDN. I won't say its perfect, but it is hard to find a better source of documentation. I have dug through docs from companies like adobe, rimage, qualcomm, and apple, and its much more painful that MSDN docs..

[Jenner]

I have no problems using the MSDN. I won't say its perfect, but it is hard to find a better source of documentation. I have dug through docs from companies like adobe, rimage, qualcomm, and apple, and its much more painful that MSDN docs..

True that. Most other company's sites are awful compared to MSDN for their documentation. Business Objects is pretty bad as well, but National Instruments is surprisingly good.

I tried to post something up on MSDN's forums as suggestions such as first-time users bringing up a page to select language options, simpler examples, etc... Then I get to the Live ID page to sign in... (cringes)

I don't think I have one, so I make a new account... it says my email is already registered. Ok, must have been a while ago... why not, send me my password! T plus 4 hours... Still waiting.