Documentation needs improvement

[martijnhoekstra]

This is a vague ticket written at the request of @jvican (https://gitter.im/scala/center?at=5a95acdbe4d1c63604a0e5bb)

Obviously 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.

But I do believe there is still a ton of work still to do.

Tour

In 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 (vals), tuples and mixins.

These 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.

vals, 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.

Meanwhile, 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.

Guides

The 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.

In 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

A 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.

FAQ

The 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.

[SethTisue]

lots of good ideas here, thanks Martijn! I hope people will dig through this and find specific things they're interested in tackling.

[SethTisue]

note that all these things (tour, guides, FAQ) actually live over in https://github.com/scala/docs.scala-lang, not in this repo

I'm labeling as "good first issue" since there are multiple good first issues here that somebody could tackle

[mghildiy]

I would like to work if this is already not being looked into.

[jvican]

@mghildiy Great, talk to me or @martijnhoekstra if you have any questions 😄

[mghildiy]

I would first work on Tour(in repo it is _tour, just to be sure).
From second para in Tour section above I can figure out that following needs to be added to tour:
HKTs(higher kind types)
(G)ADTs
type members
tuples

I am not very clear about third and fourth para.

Also, as I gather material to be added I would keep posting it here so that people can verify with quality of the material.
Please let me know if you think there is a better alternate way of doing it.

@martijnhoekstra
@jvican
@SethTisue

[jvican]

Do we want to add HKT and type members and more advanced features in the tour or should we leave them out and focus on improving the quality/quantity elsewhere?

@martijnhoekstra Your lead here would be much appreciated. I feel you have a better understanding of the current docs and a much clearer idea of how to improve them than I do.

[martijnhoekstra]

Sealed type hierarchies/ADTs is for me one of the key patterns/features in scala, and should IMO be a fantastic addition.

HKTs are a feature that really sets scala apart from other languages like kotlin, an should IMO therefore also be part of the tour, though maybe a bit towards the end.

[mghildiy]

Thanks for inputs.
Would start working soon.

[SethTisue]

+10 to a tuples section, this is a basic thing that should be covered, especially since our tuples are sharply different from Python tuples which is where folks are likeliest to have encountered the word "tuple" before
+1 to a HKT section
+1 to an ADT section (but not GADTs IMO, except maybe for maybe like one sentence with a link to elsewhere)

type members, there probably ought to be a section, but it seems to me like it could be a hard one to write, since type members and type parameters overlap heavily and explaining why type members are their own thing seems challenging to me. (maybe there's good material on this on Stack Overflow that we could borrow?)

[martijnhoekstra]

Agreed on the tuples as a high priority addition.

Also +1 to keeping type parameters and type members close together.

[mghildiy]

I have added tuples to tour. I have few questions:

1. Where in the sequence I should add tuples?
2. I assume number is inserted by build process.Right?
3. Can I make a commit with just tuples, adding other topics later on?

[mghildiy]

@jvican, @SethTisue , @martijnhoekstra

[martijnhoekstra]

@mghildiy I would suggest to add tuples near the beginning, maybe right before "Class Composition with Mixins"?

I'm not entirely sure about the build process -- I assume the same.

A piecemeal approach with tuples now and other topics later also sounds great, so that PRs remain independent and discussion on one shouldn't bog down another.