RTFM: A Critique on Documentation

This was a comment I posted to this topic on DreamInCode forums.

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.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s