Skip to content

Latest commit

 

History

History
58 lines (33 loc) · 4.77 KB

working-with-documentation.md

File metadata and controls

58 lines (33 loc) · 4.77 KB

Working with Documentation

One of the most common pitfalls I've observed is that junior developers use StackOverflow too much. Don't get me wrong - it is an incredible knowledge base, however if you overuse StackOverflow it becomes the de facto way you learn things, which is bad. Even though answers are updated and the community standards are high, StackOverflow is a shortcut to learning. The best way to learn is from the source - the official docs and if the docs are not sufficient try going to the source code.

By using the official docs you make sure that:

  • you are reading the current version
  • with the current best practices
  • the structure of the documents isn't arbitrary - it is selected by the maintainers of the project and will help you get up to speed faster

Make sure you read the documentation and don't glance over it. Technical documentation has very little filler and skimming over it will likely lead to missing important details. This might make you feel overwhelmed by too many details, but it's okay to use something condensed when it is available. The ultimate goal should be to use the official docs/specifications.

If you copy code examples from the documentation make sure you understand what each line does. If you don't, often you will copy extra steps that aren't needed in your case which will delay your work since it will be caught in the code review.

Lastly - make sure you don't over commit. If you want to lookup a specific functionality of the library it is highly recommended to read the docs for that functionality, but don't read things you don't need - you will lose focus from the problem.

I realize the last two suggestions sound a bit mutually exclusive - read everything, but just enough. The point is to read as little as possible to unblock yourself without skipping details which may cause you to slow down.

How much is enough is a million dollar question. There isn't a formula. Use your judgment :)

Learn to find good resources

Sometimes the issues you encounter will be obscure and there may be no senior available to help you. Or perhaps understanding the documentation for a given technology is giving you a hard time? Perhaps you want a more leisure introduction to a given topic?

It is inevitable, there will be moments when you need to use external documentation and finding the best resource for your current need will save you a lot of time thus making you more productive.

Finding good resources is getting harder since in our day and age there is an ever growing heap of information we need to filter before finding the good parts.

First things first - be sure that you are looking for resources specific to what you want. There are thousands of tutorials on javascript, but if you narrow it down to DOM manipulation the number will go down. Once you know what you want, try to derive the general problem.

The next step is to make sure that you are looking for the correct version. Note - I am not saying the latest version as your project may not be using the latest one.

We've talked about how to search, but not how to filter. The filtering part is resource type specific.
In the next few sections we will have a look at the most common resource types you will encounter.

Courses

Ratings and reviews are important, but they don't cover everything.

  • When was the course last updated? If you are interested in the latest version/current best practices this is important
  • When you google the course are there strongly negative recent reviews in 3rd party places, for example reddit
  • Does the course length fit your expectations? I've seen courses on the same topic varying from 8 to 100 hours. The one worth 100 hours weren't 12 times better, they were just better time sinks. If you don't have the time to spend, it is better to go with a less rated course that fits the time you are willing to spend

Articles

Since articles are easy and quick to read, as long as the article fits the version you are working with, most of them will do the job. The truth is - the most profound realizations will come to you from a combination of reading and doing things, very very rarely from an article. Still, articles are good since they aren't constrained in length and often provide good examples.

Stack Overflow

StackOverflow is a great resource - its answers are updated and maintained by the community. Some of the answers are quite large and give great insights.

I have a few guidelines about StackOverflow:

  • Read only accepted answers as they are the maintained ones.
  • Search before asking.
  • Don't overuse it, your end goal should be to use the official documentation.

Keep in mind that Stack Overflow is not for learning, it is for finding answers to specific questions. Don’t fall into the trap of abusing StackOverflow since sooner or later you must stop depending on it.