Version & date your guides – lol?

Let me preface this by stating, I’m grateful for any information on the internet.  I fully believe more is more.  For the context of this article – when beginning – you are looking for ways to judge if a guide/article will help you.  Some rather simple information at the beginning can prevent an article from wasting the time of a beginner.

Also, I’m a rank beginner when it comes to all of this …


I can follow tutorials.  When following tutorials there was usually 2 issues I had on a recurring basis…

  1. Out of date – this far and away would trip up everything
    1. Many tutorials didn’t have a front page detailing when they which versions they used.
    2. Sometimes the version gotcha’s was a note in the body of the instructions, buried pages in & effectively not there when you are just trying to decide if you should even bother reading it.
    3. Some tutorials did not even have a date on them or even a year
  2. Small errors and a beginners lack of knowledge to judge when the issue is bigger than a typo somewhere.
  3. Contextual issues.  When someone in their tutorial thought they clearly laid out or assumed everyone reading would automatically know something.  Mainly an issue if the guides didn’t include a “who’s this for” type front page disclaiming things.  Which platforms & addons/gems etc?

Now, how to better use your time …

Since I’m beginning to get more savvy to these types of things – I’m noticing not even the rails guide holds super easy documentation.  Googled me some rails guide for routing…one of first hits splashes me down here …

railsguide

The vaulted guide here does have documentation of the version number it works with ..  but the user has to know that they can click RailsGuides header/home & then they will get the information they need to see the version.  This page is one of the better of the examples – as the information is available – even if you have to hunt for it.  I feel like it looks simple & that was the purpose, which it accomplishes.

It is still missing the date of publication & updates that new changes or last minute things might cause new users pain.

My current rule when first googling away is that if I can’t find a version/date on the guide or article – it’s worthless to me.  When I get more desperate, and there is no good help – I will default to articles/guides with the date built into the URL, then default to articles which I can click somewhere to find notes/readme/help section – but no more than a mouse click away when scanning through articles.

If the author’s skill level is too low to explain the context or mention the version – they probably aren’t going to explain the topic well enough to be helpful to you anyways!

 

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s