This is a hard lesson I had to learn as a junior developer.

I'm impatient and Stack overflow can often give me an easy solution. But just as often, it can't and I will spend 30 minutes unproductively trying things with little progress.

As I become a better developer I become more inclined to spend 30 minutes with the documentation instead.

When you're reading documentation, you also will notice other things in addition to solving your particular problem. Those other things might be helpful few minutes later and you will actually save that time. Or may be tomorrow, if your memory is good. Or may be you'll read those documentation and will actually find a better solution.

Of course most of interesting problems are not described in documentation.

Depends on how clear the documentation/usage is... and sometimes you accept that you have limited knowledge and understanding. Either way, it helps to understand what you are doing, and when in doubt look it up.

If the library documentation isn't clear then that's a clear sign that whoever created it doesn't take quality seriously and you shouldn't use it in the first place. Of course sometimes there's no alternative so you just have to deal with it.

I face a lot of anxiety from this. I'll have a task like setting up Point in Time Recovery for postgres, and I've spent days mostly just reading documentation - How postgres manages wal logs, how the internals of several popular solutions work etc.

I know it'll be worth it in the long run, but it feels like I'm wasting time because "I'm not doing anything" - I'm not committing any changes while my coworkers are busy adding new features.

I use a combination of both. I'll find something on stack overflow, and then look it up in the official documentation. In other words, treat stack overflow like a sophisticated index to a reference rather than as a reference itself.

I don't like this blanket statement ..

I would use whichever googles first and most relevant results are. Also what the issue is matters.

I don't always go to MDN for javascript issues.

But if I want to know why something is the way it is, I will.

As parent said, I don't recommend doing this. In particular, the third-party sources are unlikely get depreciation notes... So unless this is a function you know well, it is almost always better to go to official docs instead.

I will say that as a Ruby on Rails dev, where many things have changed over time, there are quite a lot of highly voted StackOverflow posts where they go into detail about what the answer is on the date of posting, then someone comments "this is different in Rails 4.1+!" and the responder will revisit the answer and revise it to include applicable advice for whichever version you might be on.

This is not granted, but it happens a lot. Although if the docs are good, you should definitely expect to find good information about deprecation notices there, too! But it's not at all uncommon for conversations about code, on StackOverflow or wherever else, to include the footnotes about what is different and what version changed it.

> I would use whichever googles first and most relevant results are.

The people who made the mistake in the OP probably did exactly that.

But what if the docs suck, as is the case with a lot of .io domain libraries?

And anything MS?

Microsoft have best most fascinating documentation in some cases. It can be fantastically detailed, while being completely useless at the same time.

Take their Azure Python API, which is clearly translated directly from C#: There's a number of functions, which according to the documentation takes a string as an input. The thing is that it won't actually take a string, it will take three or four predefined strings. Everything else will yield no result. The only thing Microsoft doesn't care to put in the documentation is which strings are actually valid and what result you can expect from them.

This is slightly unrelated but there was a time when reading the azure docs where you’d be reading a page for version 1.0 but the sidebar would take you to the documentation for version 2.0 and I actually got caught up writing a mismatched integration and it took me forever to figure out why I had done that.

microsoft's documentation for anything other than .NET stuff is absurdly bad.

i was trying to do some work with their crm solution it took me a literal week to find out how to do simple oauth -- mostly because 99% of the documentation only had .NET examples using their own framework!

Microsoft's documentation for .NET is also absurdly bad.

No, I don't want to do a full reload for every overload of a method. Yes, I might want to see where these extension methods are popping up from, out of nowhere.

had extremely good experience with microsoft documentation. and i never did .NET. even old win32 API stuff still works, unlike many APIs i know of...

Microsoft documentation was historically the gold standard for comprehensiveness and quality. If what the other commenter says (e.g. about their Azure docs) is true, I don't know if things have changed or what. Maybe a post-Nadella culture shift?

At one point they "burned the library" and broke a lot of old MSDN urls. It's now common to find dead links to MSDN on old Stackoverflow posts.

The documentation is definitely there, but finding it can be a curse. The search is worse than Google, the site is surprisingly slow for a bunch of static text, and the ability to discover something when you don't know the right search terms is poor because Microsoft name everything in the most generic way possible.

The Microsoft Docs change from MSDN was horrible (and still is). A lot of content got mysteriously mangled for no discernable reason. Their KB articles, which used to be excellent, have mostly been "disappeared" too. You can see a vast difference in quality between the newly-written pages and what was inherited from before. I find spelling and grammar errors often in the newer pages.

A lot of MS documentation now is awful. Azure stuff especially.

Sometimes there is just no usable documentation for certain things at all. I've even seen documentation for certain Azure things where it just directs you to Stack Overflow!

I guess people's expectations might have been lower? MSDN sucks along every axis I can imagine.

The content is bad: Quick, is System.DateTime[0] timezone-aware? The examples also use (the harmful and bug-prone) DateTime.Now 5 times, while DateTime.UtcNow is only mentioned once, as a minor aside.

The structure is bad: Is something part of "Core", "Framework", "Standard", or "Platform Extensions"? It's particularly ridiculous that trying to switch from Core to Platform Extensions while you're viewing a Core class (such as System.DateTime[0]), you'll get kicked over to.. Framework.

The layout is bad: Look at System.DateTime's list of constructors[1]. It takes up a whole screenful to say what Python's datetime.datetime constructor[2] paragraph says in three lines.

The design is bad: Compare the method listing of .NET's IDictionary[3] to Scala's Map[4], or Rust's HashMap[5]. Which one makes the type signatures the easiest to parse? Which one helps you get where you want to the fastest?

(Hint: For me, at least, not the one that insists on making everything a uniform shade of baby blue.)

[0]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?...

[1]: https://docs.microsoft.com/en-us/dotnet/api/system.datetime?...

[2]: https://docs.python.org/3/library/datetime.html?highlight=da...

[3]: https://docs.microsoft.com/en-us/dotnet/api/system.collectio...

[4]: https://www.scala-lang.org/api/current/scala/collection/immu...

[5]: https://doc.rust-lang.org/stable/std/collections/struct.Hash...

Python's datetime appears to have one constructor with several optional parameters, whereas .NET's System.DateTime has several separate constructors each taking a different set of parameters. The MSDN documentation is accurate and correct; your critique applies to the underlying code (which is built to be backwards-compatible to .NET 1.0, which I don't think even supported optional arguments).

The signatures that are useful when developing the library might be more complex than the ones that the library consumer would be interested in. This isn't much of an excuse when you also maintain the documentation tools.

For a similar example, Scala's old collections library had a ton of machinery to ensure that `map` and co. would specialize correctly.[0] But the user never sees that, because they added a mechanism called "use cases", that allow you to override the signature shown in the docs with a simpler one.[1]

[0]: https://github.com/scala/scala/blob/v2.12.10/src/library/sca...

[1]: https://www.scala-lang.org/api/2.12.10/scala/collection/immu...

Is the io prefix somehow related to software tech?

It is often used for the following (that I have seen - may be others):

- open source libraries - online casual browser games - development/staging environment counterpart to a .com

It's a common use-case that the best docs are provided on some dude's gist or blogpost. Devs and orgs update the code but don't bother with the forgotten docs. It happens all the time.

And the original article here is showing a real-world example of the opposite.

Namely, "some dude's gist or blogpost [or stack overflow answer]" not getting updated. Not just that they didn't but that they couldn't.

Unsurprisingly, which you should rely on depends heavily on context. It takes experience and patience to figure out which one is correct based on circumstances.

once have a working dev environment, external docs are the last place to look.

IDE type search and doc comments are much more likely to be useful.