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…
- Out of date – this far and away would trip up everything
- Many tutorials didn’t have a front page detailing when they which versions they used.
- 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.
- Some tutorials did not even have a date on them or even a year
- Small errors and a beginners lack of knowledge to judge when the issue is bigger than a typo somewhere.
- 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 …
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!