Finding a good tech tutorial

Tech tutorials are great the day they are made. Unfortunately, they are obsolete within 3 months of being created. The package manager changes, the version is now patched for a security vulnerability, or the provider they were using went out of business.

However, I'm proud to say that a tutorial I created 2 years ago (which is a millennium in tech years) is still valid today (and I still refer to it for quick hackathons).  It is on firebase (which got bought by google while I was in the process of building it).  You can see it here.

My point of this post is not to self-promote, although I think that is always an underlying point in any blog. It is simply to help you find a good tutorial for what you are looking for.

What are you looking for?

That is the first question. I have met several developers who are looking for tutorials that are VERY specific and they are searching for a technology, not necessarily a solution to a problem.  Great example, I need a tutorial of OAuth2.0 in Angular hosted on AWS with a MongoDB store. It sounds like you already know what the answer is, and you are limiting the possible solutions. How about something like: "How do I authenticate a user on a web site?" and then start diving down the solutions.

Don't think you know the answer!

If you think you already know the answer, than write the tutorial yourself. You are searching because you don't know something, or you are just validating your implementation, and that is not what I'm talking about. You can find out quite a bit more when you see various solutions and then test each one.

Software development is a science

I know that biologists and chemists are going to be offended by that statement. Mechanical, civil, chemical engineers are pissed off that we call ourselves software engineers. However, I do believe we are definitely a science. We take a hypothesis, we test it, we change it, we test it again, we let others test it, and then we have a potential proof of the concept. That is how I approach tutorials. I test them, by the letter, and see what they are missing. Do I have to create 3 accounts, 4 api keys, and 2 databases to get a hello world running?  Seems like a bad approach for a tutorial.

Tutorials are designed to be simple

They are not going to take into account scaling your site to a million unique hits a day, providing a threat assessment of potential security holes, or even tell you how to design a new site by standards that aren't even finalized yet. They SHOULD be simple, easy to follow, step-by-step instructions to get people familiar with a concept. They should provide an easy win, and enough substance that they can break it, fix it, and break it again.

Quick tangent about scalability

I love it when people approach me about building their website and they ask if the architecture can handle a 100,000 concurrent users. I almost always reply, "Wow, sounds like you are running into a great problem to have, how many users do you have concurrent at a monthly peak?". The response is usually, "Well, we haven't released the site yet, but we want to make sure we can handle that."  I always laugh. WHY? Do you really think at day 1 you will have 100,000 concurrent users? How about by day 3?  Truth is, if that is a concern, than you already have a large user base and are releasing a new product in your existing pipeline, then we can seriously have that talk. Also, if that is a concern, you can setup something on Azure that monitors and auto-scales, but that costs money that you must be willing to pay for.  Ok, enough of the tangent, back to the good tutorial approach.

Not all tutorials are created equal

The one's that work are the best. Seems obvious, but there is so much I take for granted that I don't know what is obvious for everyone. Some tutorials are so out of date that they are no longer maintained and talking about a deprecated technology (Angular 1.x). Here is another thing to be aware of, is the tutorial for mac, pc, or linux?  What are you using? You should find a tutorial that matches your system. I know you can say it "should" work on any system, but then you will need to install rimraf for a script or cross-env for node script so support an environment variable that doesn't work on a PC.

Finally, give feedback

You are the best person to give feedback to someone who created a tutorial.  Why you? Because YOU are the audience, YOU are the one ACTUALLY using it. You are the client of the content. You are why they created it. Tell them that this one line has a syntax error in it, your order doesn't work, you skipped a step and it doesn't work on your machine. Also, give them details. Don't say, "Your tutorial sucks, it didn't work on my machine." And then forget to tell them that you are running a custom OS on a rasberry pi and not sure why it isn't working. Something more like, "Hey, I started your tutorial and I got to this part and received the following error.  I'm running this on my Mac OSX running Sierra. What am I doing wrong?"  Approach is everything. I know the internet is where trolls live and sure you can blame them immediately, but do you expect a response from someone who created something for free and is getting yelled at in some forum or email for some random error?  C'mon people, be nice and ask for help.

I know my tutorial screenshots are out of date, but all the code should be good. ;-)

Thanks for stopping by and I hope this helps you vet some of the tutorials you are searching for.