I just wanted to give everyone a quick status update, and I wanted to ask folk their opinion. Below is a list of all current topics in the Scala Tour. Bold/linked topics are ones which @travis032654 has rewritten. Unbolded/unlinked topics are still in the queue.
My questions to you are:
Should we get rid of any of these topics? XML processing stands out to me.
Does anybody have any feedback on any of the documents written so far or to-be-written? Any ideas/opinions/wishes/pointers?
“Automatic Type-Dependent Closure Construction” sounds like it promises something really special, but it basically explains by-name parameters and how to use them for implementing custom syntax. Maybe that should be renamed.
The tour seems to have a few “themes”, maybe we could turn the themes in to tracks?
For example, we have
functions as values and things that have to do with that: Higher-order functions, currying, (anonymous) function syntax, Automatic type-dependent closure construction
method stuff: named and default parameters, nested functions/methods
object, classes, case classes and traits + Mix-in class composition & self types
type parameters: polymorphic methods, variance, generic classes, lower and upper bounds (but no context bounds)
Agreed – “Automatic Type-Dependent Closure Construction” jumped right out at me as sounding unnecessarily intimidating. The community pretty consistently calls that “By-Name Parameters”; I’d recommend that the tour do so as well.
I’d also recommend retitling “Sequence Comprehensions” to “For Comprehensions” – I don’t think I’ve ever heard anyone call them “sequence comprehensions”, and the current title really isn’t correct, since for comprehensions cover a lot more than just sequences. (In particular, doing a for comprehension over Option is one of the first things I usually teach, and I probably use it for Future more than anything else.)
XML processing is the only section I’d drop outright, but I agree with @martijnhoekstra that organizing the tour into tracks might make it a bit more digestible.
Finally, a bug report while I notice it (if it’s in scope for this project): on my laptop, the current Tour’s index pane runs past the bottom of my screen – and I can’t scroll it! The result is that I can’t even see the sections at the bottom.
I like the idea of sections. I agree that it would make it more digestible. Currently we have 17/33 of the guides rewritten. We’ve had two volunteers jump in and offer to write one. Check out the meta ticket on GitHub and see if there are any you want to help out with: https://github.com/scala/scala.github.com/issues/733
Maybe a bit of topic. But in the current documentation FAQ is nested under Tutorials. It should be at the top level in the list of available documentaiton documentaiton right on the frontpage. A while ago I knew there is some topic in FAQs and I just couldn’t find it. It is an auxiliary knowledge that Scala FAQ is in Tutorials. I would say these are (should be) FAQs about Scala in general not about Tutorials only.
@vladap We were actually considering getting rid of FAQ because it’s lifted from stack overflow which is more easily found on Google. I do think the Tour of Scala should be at a higher level. I’m going to propose a lot of changes to the organization of the website in the coming weeks. Please feel free to jump in and give your feedback. It will be in here https://github.com/scala/scala.github.com/pulls
When you look at the years of visitor comments on the existing tour, it’s clear that a lot of visitors are expecting to use it to the learn the language, and then are disappointed because it isn’t nearly comprehensive enough.
I think it would be best if the “Tour of Scala” were taken out of the “tutorials” section and was never referred to on the site as a “tutorial”.
To further manage expectations, I suggest we add a friendly disclaimer of sorts to the end of each section, something like “This tour briefly introduces notable Scala language features. To really learn Scala, may we suggest obtaining a Scala book?”
Yes, it’s not a tutorial at all because it’s not interactive. You really need a book to be fully productive but I do think the tour serves as a nice free reference for important concepts. I see it for two use cases:
You’re coming from another language and you want understand how Scala works in an hour to see if it’s useful.
You’re learning the language and you want a quick explanation on a subject.
Documentation sections should be up to the point they explain without going on too many tangents. Advanced use case for tutorials can be to combine multiple concepts to solve a larger problem. It should link back to documentation whenever reader might need to update his knowledge with some specific concept used.
FAQ can be useful as well as far as questions with high occurrences can be identified. They should merely link back to appropriate section in documentation. They can provide quick navigation for documentation from another angle. They shouldn’t supplement documentation itself like now though.
@vladap do you think that the current FAQs can be answered directly in the documentation? If were to click on a question and it went back to documentation it would feel like I was being told to “try harder to read the docs”. I like that Stack Overflow answers the questions directly. Perhaps we could link to the list of FAQs so it’s dynamic: http://stackoverflow.com/questions/tagged/scala?sort=frequent&pageSize=50
In retrospect mine suggestion is one extreme. The current FAQs are IMHO the other side extreme. Each question has its own page with a lot of information which I believe should be part of documentation. FAQ answers shouldn’t be that long. I think we don’t need to reinvent the wheel and rather look around. FAQ seems to be used somewhere in between. And can have various goals… Experienced developer doesn’t need complete detailed explanations let’s give him quick glance. Let’s put there some extended info. There are quick topics which doesn’t fit directly anywhere in docs. etc. As well it depends on overall goals of other parts of site. I don’t see a problem to have SO FAQ part of it.
I agree. In my opinion, the Scala documentation should have a FAQ. FAQs are very useful:
They give short replies to questions that users may think when getting acquainted with the language.
They spare several Google searches to users interested in the language.
I feel that having an official FAQ is kind of important. I really like the one that Rust has. I think Scala should have a similar one extracted from SO questions and then point to the original answers for extra details.
Agreed, provided it’s done with some discipline. The vast majority of FAQs out there, as far as I can tell, are really “this is what I want to tell you about”, and have nothing to do with what questions are actually frequent. Figuring out which questions actually come up a lot takes some research and thought – but you usually wind up with a much shorter and more useful document for it.
I agree that SO is a good place to start; I might also recommend monitoring scala/scala and users.scala-lang for a few months and keeping track of the newbie questions that come up…
Some responsive code is not working. When viewed on some small screen ( screen width < 700px), the menu becomes invisible. For instance, this page: http://docs.scala-lang.org/tour/tour-of-scala.html. Actually, all the tour pages have the same issue.
️