First of all, generally: I agree Scala documentation could be better in principle, and it would be better for Scala and the Scala community.
And I understand that in a company, immature documentation is a cost. And those who want Scala to succeed want to reduce such costs.
Even so, don’t take this the wrong way, but a company using open source isn’t a customer who has paid a product and gets a warranty for it. Yes, people working on Scala do their best. But no, there aren’t millions of such people, and there’s tons of work.
I love Scala, and I’d love people to use it, but I can’t tell you its advanced features have the easiest learning curve, or that its documentation is as good as it could be. As Steve McConnell writes, unfortunately being “early adopters” does mean facing rough edges. I suspect most companies using Scala just try hiring enough Scala experts or buying good Scala training.
While this is a side point, and most programming documentation is guilty of much worse crimes: I agree with @vladap on this general point—this is standard advice when writing academic papers. I also agree on this specific example—yes, usually you’d learn infix syntax before implicits, but I know exceptions first-hand. You can’t discuss implicits without types, but infix syntax is an irrelevant obstacle.
I also agree with @S11001001 though: after fixing this issue, these docs would be better, but still hard for most beginners. As you yourself point out, there are likely bigger improvements possible here.
Changing the example to use
.add rather than
+ (or some other method where infix syntax is less appropriate) would not create obstacles to making the point.
So if anybody sends a PR to fix this (without unrelated changes), feel free to ping me for positive support.
One note though: such advice works best if one is willing to contribute rather than expecting others to. I’ve offered my support, so you know that a PR has a chance.
And I don’t just mean “you should contribute because this is open source”, but “you should contribute such things because sadly few have time to write docs at all, and even fewer have time have time to make them as beginner-friendly as possible.” Also, I haven’t yet seen computer science courses teaching technical writing. I heard there was the idea of hiring (where?) a technical writer to write Scala docs, which would be excellent, but I don’t think it’s easy.
Implicit conversion which adds extension method through implicit conversion into the picture brings it to another level, type inference even more.
Well, that is a standard pattern in Scala which should be explained somewhere. But if you can explain implicit scope without introducing this pattern, and then explain it elsewhere, go ahead.
Now, talking about bigger issues:
I think I agree with @vladap also here—I’ve seen examples of implicits that work (in Odersky et al.'s Programming in Scala), tried to invent my own patterns that should have worked (and which IIRC weren’t unreasonable, but I was still a Scala padawan), failed, and then stopped experiments. I have never seen “rules” or “best practices” stated at all, much less widespread. I’m happy to be proved wrong by actual links, preferably to “important” blogs—but anything, really.