Damn Good Documents Make the Difference

August 18, 2014

When I started out coding as my Senior Developer was my buddy. We worked in a hybrid environment; we would write C# and UniVerse Basic code. I wasn’t that comfortable with Basic and would rather just code away in C#. So when I was assigned to him I thought to myself this was going to be so awesome, I can ask him anything and he will just have the answer. Well, I was mistaken every time I asked him something his first reply would be “Have you read the documentation?”, my response for the first two weeks would always be “No, I haven’t.” So with my tail between my legs I would go and read the UniVerse documentation.

Him sending me back to read the documentation was the best thing ever to happen to me. When you go a read API documentation, you tend to grasp it much better than just being told to do things in a certain way. What ends up happening is a lot of tests, or throwaway code is written so that you can learn this API. That means that you have a reference and some working code the next time you run into a similar problem.

Now in the C# world I don’t think many would argue that the MSDN documentation is just plain bad. The guys over at Microsoft could have done a much better job then they have. In my opinion, the one Microsoft property that has good documentation is the ASP.NET site. They have decent and recent tutorials, and the articles are well written. What is missing is try API documentation, the no frills kind of stuff, the type of documentation where it’s straight to the point with concise examples.

Over the last few weeks I have found myself reading a lot of Ruby code, I believe this is a good way to learn. However, just recently did I discover what great documentation is provide to [Rails][rails] developers on the Rails Guides website. I love reading their documentation; that is the sort of documentation that every library should have.

Need to get started with [Rails][rails]? That’s there and is well-written need help with Migrations? How about Views? Having issues Mail or your Controllers? Or do you just need some pointers on testing? Well, look no further than the Rails Guides website.

What impresses me is how well these documents are written, clearly a lot of time and effort has gone into making this world class. Not only is Ruby a great language to use, not only does [Rails][rails] make web development a pleasure but now they even make working with their documentation as easy as pie. I can now see why Ruby and [Rails][rails] are so popular, there is a lot of efforts that goes into making this a wonderful eco-system and it is no wonder that all Rubyists seem like the happy hippy trippy kind of people.

So do yourself a favor have a look at the Rails Guides website that is what documentation truly is.

Discussion, links, and tweets

My name is Deon Heyns and I am a developer learning things and documenting them in realtime. Python, Ruby, Scala, .NET, and Groovy are all languages I have written code in. I appeared in the New York Post once. I host my code up at GitHub and Bitbucket so have a look at my code, fork it and send those pull requests.

comments powered by Disqus