6 Replies - 4618 Views - Last Post: 25 July 2011 - 01:21 PM

#1 AdamSpeight2008  Icon User is offline

  • MrCupOfT
  • member icon


Reputation: 2216
  • View blog
  • Posts: 9,352
  • Joined: 29-May 08

R.T.F.M. Huh?

Post icon  Posted 25 July 2011 - 10:13 AM

To help those who have difficultly understanding the documentation.
Especially MSDN.

What aspects do you find difficult?
What parts do you understand?

Post your helpful tips to understanding and reading them.
Is This A Good Question/Topic? 3
  • +

Replies To: R.T.F.M. Huh?

#2 zyphlar  Icon User is offline

  • New D.I.C Head

Reputation: 0
  • View blog
  • Posts: 2
  • Joined: 19-November 08

Re: R.T.F.M. Huh?

Posted 25 July 2011 - 11:17 AM

The most frustrating part of R'ing T F'ing M is usually "ok but how do I do this thing I want to do?" I see MSDN now has a Remarks section with Common Tasks, so as long as what you want to do is there I could see that being an improvement over most documentation.

The .Net Framework does a lot, but it falls short of being an operable framework for a lot of real-world domain-specific stuff. For example XML and databases can still be a pain compared to something like Ruby/Rails, and its GUI is pretty opaque about how it accomplishes its magic sometimes (hey if I create fifteen wrapper classes I'll come out the other end with a custom control, right?) The opinionated nature of the newer frameworks is really refreshing because it allows some sort of focus. Should I code up a 3D game engine in C#? How about a website? How about a server management script? The answer is kinda "sure" to all of these for C# and that's its weakness.

The other thing is examples. Look up the examples for DataGridView on MSDN. You'll have to scroll past the list of every single method and property in the class. Now I know DataGridViews better than most, having made an Excel-like app, and can tell you this example is mostly Greek to me. Sure it's initializing stuff and setting properties, but which does what and when? The contents of the SetupLayout and SetupDataGridView functions would normally be put in your form's code-behind and beginners (i.e. the ones who get told RTFM) will feel more comfortable editing these things there than being told to code them into their controller by hand. Not to mention this example also has the Main() entry point, which works but makes the MVC in me cry. Sure it's just an example, but beginners learn by these examples and here they're learning that initializing your control, putting in any business logic, and running your Main in the same file are cool. No comments, either.

In my opinion a language is made or broken by its examples (and tutorials, free training, etc.) For example just thinking about PHP makes my stomach wrench, because the code others write (and in some cases, I write) is just awful, and it's all because of the documentation's examples and the blogs/tutorials out there. I'm lucky to get something working in PHP, forget about getting it to work RIGHT, and doing it cleanly/maintainably is foregone. I might as well be writing my website in Perl or ASP, sometimes. Making your language focused to a task and opinionated about the right way to do it is invaluable in helping the world use your language correctly.

Imagine if hammer makers had no design opinions about how their hammers should be used or which one was right for which situation; or maybe they did, but didn't include that prominently in the product labeling. We'd be stuck in a world where deadblow hammers were used for hanging photos and tack hammers were used for auto body repair; a pitiable world indeed. Software tools are the same.
Was This Post Helpful? 0
  • +
  • -

#3 smohd  Icon User is offline

  • Critical Section
  • member icon


Reputation: 1752
  • View blog
  • Posts: 4,409
  • Joined: 14-March 10

Re: R.T.F.M. Huh?

Posted 25 July 2011 - 11:26 AM

I use MSDN documentation and other tutorials( mostly from DIC and Code Project) since I started to learn VB.NET(Like 9 months now). What I have experienced from it(MSDN) is the following:
- I got difficult to understand them at the beginning but now is like a drink of water. Now what I think is that new to MSDN get difficult to understand them because they always search the wrong thing(As I was doing before). Because I experienced that MSDN has two types of docs, one for explains how the class(or may be function) is(and it is for advanced learners) and the one how to use(which is good for begginers....

- What to do: It is important to know what you need while there and try many subject keyword to get good resources. Also we may advice newbies to use Offline Training Kits
Was This Post Helpful? 0
  • +
  • -

#4 AdamSpeight2008  Icon User is offline

  • MrCupOfT
  • member icon


Reputation: 2216
  • View blog
  • Posts: 9,352
  • Joined: 29-May 08

Re: R.T.F.M. Huh?

Posted 25 July 2011 - 12:07 PM

This question is mainly aimed at learners.

What about when replies link to specific documentation?
What are you (the O.P.) expecting to find?

The Basic Guide to MSDN

Let's use the following MSDN: String Class

All of the pages of MSDN have the following sections. (Note the sections can be collapsed.)

  • A brief description of about the class
  • Inheritance Hierarchy
    This tells you what the class inherits.
    System.Object 
      System.String
    
    



  • Syntax
    Some technical information on traits of the class.
    'Declaration
    
    <SerializableAttribute> _
    <ComVisibleAttribute(True)> _
    Public NotInheritable Class String _
    	Implements IComparable, ICloneable, IConvertible, IComparable(Of String),  _
    	IEnumerable(Of Char), IEnumerable, IEquatable(Of String)
    
    


  • Constructors
    This you all of the possible overloads that can be used when the class is initialised (New-ed up)

  • Properties
    The properties of the class object.

  • Methods
    Functions and Subroutines to class exposes.
    Often it links to pages describing how to use that particular method.

  • Opereators
    This are the "arithmetical symbols" the class exposes.

  • Extension Methods
    A bit like Methods, but are defined separate from the class.

  • Explicit Interface Implementations
    What Interface the class implements.

  • Remarks
    Comments about using in the class.
    - Things to watch for or be aware of.
    - Often includes usage examples.

  • Version
    What version of the frameworks is the this about.

  • Platform
    What OS can this be used on.

  • Thread Safety
    What issues (if any) if try to use one multiple threads

  • See Also
    Things you may what to also look up.

  • Change History
    What has changed in the documentation

  • Community Content
    User comments.

This post has been edited by AdamSpeight2008: 25 July 2011 - 12:10 PM

Was This Post Helpful? 3
  • +
  • -

#5 Curtis Rutland  Icon User is online

  • (╯□)╯︵ (~ .o.)~
  • member icon


Reputation: 4312
  • View blog
  • Posts: 7,467
  • Joined: 08-June 10

Re: R.T.F.M. Huh?

Posted 25 July 2011 - 12:17 PM

I think this is an important breakdown, since the MSDN can be information overload to a new programmer. They have to know how to process the info dump they're about to recieve. If you edit the tutorial into the top post, I'd like to link this in the C# resource thread.
Was This Post Helpful? 1
  • +
  • -

#6 AdamSpeight2008  Icon User is offline

  • MrCupOfT
  • member icon


Reputation: 2216
  • View blog
  • Posts: 9,352
  • Joined: 29-May 08

Re: R.T.F.M. Huh?

Posted 25 July 2011 - 12:22 PM

I've just wrote a tutorial.
Pending, I think it may auto-approve (If I've the correct privileges)

This post has been edited by AdamSpeight2008: 25 July 2011 - 12:25 PM

Was This Post Helpful? 0
  • +
  • -

#7 Sergio Tapia  Icon User is offline

  • D.I.C Lover
  • member icon

Reputation: 1251
  • View blog
  • Posts: 4,168
  • Joined: 27-January 10

Re: R.T.F.M. Huh?

Posted 25 July 2011 - 01:21 PM

Just wanted to pop in and say MSDN is a fantastic resource that is mostly overlooked by new programmers in favor of other websites.

It used to be cluttered and crappy (circa 2007), but now it's phenomenal. I really don't know what I'd do without it. Buy a book maybe? Blegh!

Good topic, let's share the knowledge of this website, it rocks! :lol:
Was This Post Helpful? 0
  • +
  • -

Page 1 of 1