{"action":"created","issue":{"url":"https://api.github.com/repos/scala/scala-lang/issues/850","repository_url":"https://api.github.com/repos/scala/scala-lang","labels_url":"https://api.github.com/repos/scala/scala-lang/issues/850/labels{/name}","comments_url":"https://api.github.com/repos/scala/scala-lang/issues/850/comments","events_url":"https://api.github.com/repos/scala/scala-lang/issues/850/events","html_url":"https://github.com/scala/scala-lang/issues/850","id":300958284,"node_id":"MDU6SXNzdWUzMDA5NTgyODQ=","number":850,"title":"Documentation needs improvement","user":{"login":"martijnhoekstra","id":882449,"node_id":"MDQ6VXNlcjg4MjQ0OQ==","avatar_url":"https://avatars2.githubusercontent.com/u/882449?v=4","gravatar_id":"","url":"https://api.github.com/users/martijnhoekstra","html_url":"https://github.com/martijnhoekstra","followers_url":"https://api.github.com/users/martijnhoekstra/followers","following_url":"https://api.github.com/users/martijnhoekstra/following{/other_user}","gists_url":"https://api.github.com/users/martijnhoekstra/gists{/gist_id}","starred_url":"https://api.github.com/users/martijnhoekstra/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/martijnhoekstra/subscriptions","organizations_url":"https://api.github.com/users/martijnhoekstra/orgs","repos_url":"https://api.github.com/users/martijnhoekstra/repos","events_url":"https://api.github.com/users/martijnhoekstra/events{/privacy}","received_events_url":"https://api.github.com/users/martijnhoekstra/received_events","type":"User","site_admin":false},"labels":[{"id":585988382,"node_id":"MDU6TGFiZWw1ODU5ODgzODI=","url":"https://api.github.com/repos/scala/scala-lang/labels/good%20first%20issue","name":"good first issue","color":"d4c5f9","default":true}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":10,"created_at":"2018-02-28T09:52:58Z","updated_at":"2018-09-09T03:16:16Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"This is a vague ticket written at the request of @jvican (https://gitter.im/scala/center?at=5a95acdbe4d1c63604a0e5bb)\r\n\r\nObviously I'm not the final arbiter of what constitutes good documentation. These are just things that I feel are lacking in the current documentation. From my perspective the documentation has improved a lot over the last year or so - recently, someone even qualified the documentation as \"so good\". I'm really happy about that, and I'm thankful for the hard work many have put in to it. \r\n\r\nBut I do believe there is still a ton of work still to do.\r\n\r\n### Tour\r\nIn general the tour does a reasonable job of giving an overview of the language. However, when I would be asked what sets scala apart as a language, to me it would be HKTs, implicits (and the type-class pattern they enable), pattern matches, for comprehensions, sealed types ((G)ADTs), and type members. That's where scala shines when compared to languages close to scala. Things that are (at least somewhat) standard, but also things that scala does and are nice are type parameters, first class functions, immutable references (`val`s), tuples and mixins.\r\n\r\nThese are things I would expect to see in a tour of scala. In the current tour, missing are HKTs, (G)ADTs, type members and tuples.\r\n\r\n`val`s, first class functions and mixing in traits are part of \"basics\" (should they be?) implicits are split between two tour parts and a FAQ entry, and are still rather incomplete. Type parameters/generics/parametreric polymorphism are sort of \"Generic classes\", but obviously not just classes.\r\n\r\nMeanwhile, regex extractors have their own section, while from my perspective they are a neat party trick to go along with extractor objects (which could be part of the pattern matching section or track itself). Compound types (http://docs.scala-lang.org/tour/compound-types.html) link at the bottom to abstract types (http://docs.scala-lang.org/tour/abstract-types.html) which seems to be an isolated mini-track on its own, together with traits and self-types. AFAICT it's only reachable from here.\r\n\r\n### Guides\r\nThe guides feel ad-hoc and haphazard to me. The collection of guides feels incoherent - just a few things someone pointed a magnifying glass at and worked out.\r\n\r\nIn my ideal world, guides would consist of in-depth language guides, like a less formal, more elaborate human readable language spec on the one hand and programming guides, which deal with patterns and best practices on the other. A good example of the first kind of guide is IMO http://docs.scala-lang.org/overviews/core/value-classes.html. A good example of the second kind is IMO http://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html\r\n\r\nA good example of neither are the first two listed guides: http://docs.scala-lang.org/overviews/collections/introduction.html and http://docs.scala-lang.org/overviews/core/architecture-of-scala-collections.html, the first of which would IMO make for an excellent stand-alone blog post/article, and the second is a library usage guide, which should IMO either be part of the scaladoc of the `scala.collection` package, or also be a stand-along blog post/article linked from the scaladoc.\r\n\r\n### FAQ\r\nThe FAQ shouldn't (have to) exist, and if it does exist, entries should be short and consist mostly of links that tie individual guides and/or articles together."},"comment":{"url":"https://api.github.com/repos/scala/scala-lang/issues/comments/419687699","html_url":"https://github.com/scala/scala-lang/issues/850#issuecomment-419687699","issue_url":"https://api.github.com/repos/scala/scala-lang/issues/850","id":419687699,"node_id":"MDEyOklzc3VlQ29tbWVudDQxOTY4NzY5OQ==","user":{"login":"mghildiy","id":10056406,"node_id":"MDQ6VXNlcjEwMDU2NDA2","avatar_url":"https://avatars0.githubusercontent.com/u/10056406?v=4","gravatar_id":"","url":"https://api.github.com/users/mghildiy","html_url":"https://github.com/mghildiy","followers_url":"https://api.github.com/users/mghildiy/followers","following_url":"https://api.github.com/users/mghildiy/following{/other_user}","gists_url":"https://api.github.com/users/mghildiy/gists{/gist_id}","starred_url":"https://api.github.com/users/mghildiy/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mghildiy/subscriptions","organizations_url":"https://api.github.com/users/mghildiy/orgs","repos_url":"https://api.github.com/users/mghildiy/repos","events_url":"https://api.github.com/users/mghildiy/events{/privacy}","received_events_url":"https://api.github.com/users/mghildiy/received_events","type":"User","site_admin":false},"created_at":"2018-09-09T03:16:16Z","updated_at":"2018-09-09T03:16:16Z","author_association":"NONE","body":"I have added tuples to tour. I have few questions:\r\n\r\n1. Where in the sequence I should add tuples?\r\n2. I assume number is inserted by build process.Right?\r\n3. Can I make a commit with just tuples, adding other topics later on?\r\n\r\n"}}
{"actor":{"display_login":"mghildiy"}}