Scala 3 Book - chapter re-ordering

[xhudik]

Scala Tools contains wonderful info on how to set up your first projects, what tools should be used for what.

At the moment, the chapter is served at the end of Scala 3 Book. I'd guess to put it in the beginning (after: hello world and before The REPL) would make much more sense.

Unfortunately, I dont know where the content of the book is located so I cannot make a pull request :)

[SethTisue]

@alvinj ?

[alvinj]

I’d like to include @b-studios here as well, because I wouldn’t want to change the ordering without including him.

If I remember right, we were thinking of those last five chapters (everything after Concurrency) as being Appendix/Reference-like chapters. But one of the problems with that is that there’s not an easy way to make it appear as an appendix.

Because it’s a little long, I also didn’t want to slow the “Learning Scala” process at the beginning of the book. I wanted to focus on Scala early, and Tools later. But it could be moved between A Taste of Scala and A First Look at Types. If I had a vote, I’d leave it where it is and see what we can do about making the “Appendix” part more obvious, but I’m open.

[xhudik]

hmm, yes if there is a good appendix - it would make sense to make a link from Hello world chapter. If not, I'd put it as soon as possible - before the real learning will start(somewhere inside Taste of Scala). When I personally read the book I wanted to test things described in the book, therefore having ready whole toolset seems to me important... But that might be just my subjective feeling.

Another thing what can make reading/testing easier is Scala worksheet - I use it in IntelliJ, not sure whether they can be enabled in Sublime text or some other IDE. Maybe having a note about it somewhere in Scala 3 book would make sense as well ...

[xhudik]

@alvinj what about a link within Hello world: https://github.com/scala/docs.scala-lang/pull/1964 I just dont know how to make a link between chapters (it is hardcoded for now)

[alvinj]

I wanted to test things described in the book

We definitely wanted to make some/most of the code testable on each page by integrating Scastie or ScalaFiddle, but I don’t know the status of that effort.

You can see how ScalaFiddle is integrated on this Scala Tour page. But that uses an older approach, and I thought we were going to use something different, but I don’t remember the details. It had something to do with how Markdown code blocks would be annotated.

[alvinj]

@xhudik I’m sorry, my multiuser Git skills are still pretty lame, but if you add this to the very bottom of the taste-hello-world.md page:

[scala_tools]: {% link _overviews/scala3-book/scala-tools.md %}

Then I would use wording like this in the area where you have your change:

> More information about sbt and other tools that make Scala development easier can be found in the [Scala Tools][scala_tools] chapter.

If you look at the source code for this page, that’s the link style we are using. That will make it easier if/when this book gets moved to a new location.

Thanks!

[xhudik]

@alvinj - cool - I tried it: https://github.com/xhudik/docs.scala-lang/blob/patch-18/_overviews/scala3-book/taste-hello-world.md (pull request: https://github.com/scala/docs.scala-lang/pull/1964 ) Is it OK?

And yes, Scastie and these things can improve readability a lot. Thanks for the info!

[alvinj]

@xhudik (and @SethTisue) Yes, that looks good to me. Thanks for this, it’s a nice improvement!

[b-studios]

Yes, thanks for adding the link. One other option would be to move it out of the book into a separate guide (https://docs.scala-lang.org/scala3/guides.html).

[xhudik]

@b-studios, yes - having a small guide on how to work within scala ecosystem: what IDE are available, what plugins are needed to create a scala project, how to test your programs, what profilers can be used,... would also definitely make sense. I mean some practical, down-to-earth guide for practitioners who want to work with scala (beginners as well as daily users)

Then guides like Scala (3) book will just link to this new guide.

[alvinj]

I’m a little swamped at the moment finishing the Cookbook, but I agree that this would be a good guide!