This first step is going to sound trivial. It isn't as trivial as it seems, and a shocking number of people manage to skip it.
Before you do anything else, you must understand WHY the tool or concept you're researching exists. If its purpose is not clear to you, you must clarify that first. Find a short overview of the tool or concept.
A general understanding of its purpose will help orient you as you attempt to understand/use it. The tool/concept has a purpose. If you can't articulate to another person what that purpose is (in a way that feels like it would be genuinely useful to YOU), there's a good chance you will struggle to use the tool effectively.
- WHY does this tool or concept exists?
- More specifically, what problem(s) does it solve?
Proof that this is not as obvious as it seems: Math is a tool. What is the purpose of math? As a tool, what problem(s) does it solve?
- Most people have never asked themselves this question -- "why math?"
- Even though they "did" math in school for years.
It is much easier than one might think to start trying to use something before understanding what its purpose is.
Go to the documentation and look for any sections with names like those listed below. There is almost always a "Getting Started" page. Some are longer than others. Depending on time constraints (and whether or not you'll be using that tool a lot), either read or skim them:
- Getting Started
- Quick Start
- Introduction
- Philosophy
- Overview
- etc...
For common Computer Science concepts: Wikipedia is often a good place to start.
Otherwise: try to find an article or post on the topic using the Aim Before Shooting Approach to Googling (see section with the same name farther down in this document).
Implementing a new tool in the environment of an already complex application often makes understanding that tool FAR more challenging than it needs to be. Frequently one ends up with horribly intractable questions:
Is this not working because I'm using Redux? No wait! Maybe it is my Webpack config! Or is it Babel? Maybe it's because I'm running the tool in Docker? Or maybe it's because of something on AWS! AHHHHHHHH!
Instead of learning/experimenting amidst the complexity of so many variables, it is often helpful to create a small, controlled sandbox for yourself -- get the most basic demo of the tool working.
OR
Disable/comment out large portions of your app to test the tool in a less complex environment.
Use the SIMPLEST implementation possible until you get SOMETHING RUNNING.
Often, documentation will have an example/guide/demo of the simplest possible implementation of the tool. DON'T just read that example -- get it actually running!
With a basic sample actually running in front of you, you can quickly TEST your theories about how the tool works while reading the documentation.
- Try things.
- See how they work.
- Break things.
- See how they break.
Hint: Only change ONE thing at a time, otherwise it’s hard to know if the result is due to change A or change B
If the phrasing for a feature in documentation is unclear, rather than attempting to perform some complicated exegesis of the text, simply try that feature in your demo sandbox.
What does this configuration actually do? Oh wow! Pretty colors! Does it break if I add Redux? Nope, it just becomes AWESOME :) How about if I add a Styled Component? ...well that broke everything. Guess I know what the problem was in my app. (Damn you, Styled Components!)
Once you do actually get some feature working, if you added several unfamiliar pieces of code, make sure those pieces actually do what you thought -- make sure they're actually necessary.
One simple strategy is to try removing/altering each line to check if that line is actually necessary for the feature to work.
Often we dig too deeply into the FIRST link we open off a Google search. As a result, it isn’t until four links and (20 or 40) minutes later that we finally get to a better resource for solving our problem.
A better approach is to race through a rapid-fire survey of several pages before ever diving in deep.
The following approach can help to more quickly develop a sense of the landscape and zero in on a higher-relevance resource.
- Enter a good Google search query.
- On the results page, without thinking too hard, quickly open approximately 5 of the most promising links as tabs (on mac:
CMD + click the link) -- this should take under 30 seconds. If a link looks even remotely relevant, just open it. - Now, (AFTER opening all the relevant links as tabs) scan through each open tab as fast as possible. Spend no more than a minute on each. Read only enough to get a general sense of how relevant the page is (often this means reading only headers).
- Usually, one or two pages will stand out as better resources than the rest. (You will also notice that there are some topics that ALL of the pages touch upon, while there are other topics that maybe only one of the pages will mention; chances are good that the topics that every page mentions are the MOST important topics.)
- Now that you actually have some frame of reference for what resources are available, dig into the one that seems the MOST relevant.
Use command/ctrl + f to search for the term you're looking for on the page. Nuf said.
Use Google to search a site:
site:www.someDomain.com my search query here
Google's search usually performs better than the search bar on documentation websites.
Tech changes fast! Don’t look at outdated advice! The best solution to your problem in 2014 might not even work anymore!
If the documentation has a table of contents, it is often a good idea to scan the WHOLE list to give yourself a general sense of what is available to you with this tool. (Please skip this step if you like rewriting functionality that has already been implemented for you.)
Oh wait, this class already has a method that contains all the functionality I was painstakingly writing myself….
Make sure you are using the right guide/resource/API documentation for the right version. Don’t look at Mysql version 8 docs for a version 5.7 build!
Never code for more than 15 - 20 minutes without finding a way to get feedback from the computer about whether your code is working. Coding without feedback is like driving a car blind. You'll end up somewhere, but its not likely to be where you wanted to go, and along the way you're definitely going to break things.
If you don't know how to get feedback for the thing you're working on, your first task should be "figure out how to get feedback!"
By frequently testing your code (usually, but not always, a console log), you will save an immense amount of time debugging. It is a horrible experience to write code for 2 hours, run the code, and then discover the application crashes immediately. Where was the bug? It could be anywhere in the work you did over the last 2 hours!
Your ability to test frequently will be directly affected by how long it takes you to test, how long your feedback loop is. If you have to write the code, put it on a flashdrive, drive 45 minutes to some other computer, and then run the code there, you will almost certainly not test your code every couple minutes (and you should test that often). You want to keep your feedback loop short. If testing your code is starting to feel like a huge pain, you probably want to spend a couple minutes devising a faster way to get feedback (maybe automate something you've been doing manually).
Prefer sources at the top of the following list. Move on to the lower sources only as necessary.
Using documentation IS A SKILL. There are common patterns and conventions used in documentation that will only become recognizable through experience! Get that experience sooner rather than later.
Documentation is the most likely place to find CURRENT valid approaches to using the tool.
Documentation will more reliably describe best practices for the tool.
Documentation often has useful guides or samples that are NOT WRONG. By comparison, that Medium or Hacker Noon article written by the brand new developer who is trying to pad his LinkedIn profile is not always the most reliable source.
The documentation was written by the person/people who actually built the tool (aka, knowledgeable developers)! And they WANT you to use it, so even though it might not always feel like it, they are trying to show you how best to use that tool!
TIP: The problems you are tasked with solving as a software engineer will very quickly become so complex and idiosyncratic that no person has ever solved exactly the same problem you’re facing, and certainly nobody has ever written a Medium article about it. Develop your documentation reading skills before it’s too late...
If you're dealing with a very specific, tool-related issue, this is the next most reliable place to look.
Again, the actual creator of the tool (or a developer on the team) is often the person who answers questions in the Github Issues area
These should not be your first choice, but can help in a pinch, or they can help you get a sense of the landscape you're working in.
Don't spend forever looking for just the right article or blog post. If you're really struggling to find a good resource, you might make better time just diving into the source code.
If you DO get a potential answer from one of these sources, it is advisable to look that solution up in the documentation.
Don't just copy and paste lines of code. Question marks in your code will come back to bite you, guaranteed :D
If you really don't have time for due diligence, leave a comment next to the code that is not understood (so you know where to look first when your application explodes for apparently no reason)
Don't be afraid to dive into the guts of some program/library/tool. You know more than you know.
The source code of a library is not off limits.
- You can read it.
- You can even modify it!
- Add a console.log
- Test a theory
- Break a piece and see what happens
- Getting some cryptic error message from a library? Search (cmd + f) for that string in the source code. You can often figure out what it was doing when it threw the error. Even when the code is in a language you’re not familiar with, you can often figure out what it’s meant to do.
If you don't have a more knowledgeable person to ask for help and you've exhausted all the above resources, it's time to post a question to some online forum. Reddit, and Stack Overflow can help you through some pretty tough problems. Before you take this step, however, you need to have researched the problem space, developed several theories for how to move forward, and tested those theories. That is how a developer solves problems, and you're unlikely to receive help from others if you have not given that process your best effort. It is recommended that when posting a question to such a forum, you list all the things you researched and tested on your own.