What was your experience with Play documentation as a new user?

Thanks for the feedback, @Sylvain.

It looks like we have a problem with language management at the website. Do you mind opening an issue in https://github.com/playframework/playframework.com/ so that we can investigate later?

I appreciate if you can open an issue for this problem too. I have a good idea of what could be possibly happening but don’t have the time to solve it right now.

Best.

As I started looking into using sbt-web more for things such as digest, gzip, uglify, etc… it seems the documentation on sbt-web topic is a bit light. There is a paragraph or two about it (e.g. asset fingerprinting), but I found it a little confusing on what I need to put into build.sbt and plugins.sbt (or what I do not need). The best doc on this topic was actually a blog written by someone else I found via Google. The play-java-sample application also does not seem to cover this.

Done for both issues ;-)

I think that the documentation is for developers that already know Play. For a beginner is a little complicated to understand how to use Play in a real application. In my opinion need more real examples about authentication, how to secure actions, how to interact with databases sql and nosql. I wrote a lot of application using Play, but for more things I’d to search via Google especially to interact with mongoDB. I understand that this is not really related with Play but could help new users to become interested to Play.

2 Likes

Hey @Sylvain,

Just to let you know that the search issue is now fixed. :slight_smile:

Best.

@marcospereira yes it’s fixed :-) Many thanks. Sure it will be helpful ^^

Like other users have mentioned, it seems the documentation is more for people familiar with Play. It is just small things here and there, small pertinent steps which make things work etc. It is hard to for an experienced person to document processes and actions they have performed hundreds of times, steps get missed. Plus it would be great if the Play documentation added a “User contributed Notes” section. This was always my absolute most favorite part of the PHP language. The fact that users can contribute as they make discoveries, really, really adds to the clarity of the documentation by a long shot. Look at the User Contributed Notes section.
Notice how users have added their notes. If you look throughout the docs you will notice users even note which versions of PHP their notes pertain too, when it is something affected by a major change. Play documentation gives you a link to some forum, where you then must search for anything you can find related to your issue. Having a “User Contributed Notes” section would greatly improve the documentation, especially for new users. Plus it’s not like there are millions and millions of people learning/using Play Or Scala, so this feature is less likely to be abused. It is nice to have info about the source right at the source.
So if there is any improvement that I think would make the most difference for Play, it would be adding a “User Contributed Notes” Section. Other than that I actually print some of the documentation and keep it in a 3 ring binder and take notes on notebook paper. :man_office_worker:

Having 2 different layouts for the Api documentation is also confusing. I don’t like this version it is too hard to find things. https://www.playframework.com/documentation/2.7.x/api/scala/play/api/controllers/index.html

This version is much more obvious, the whole expanding section thing with the other sucks. I find this version to be easier to find things and recognize where classes are. https://www.playframework.com/documentation/2.6.x/api/scala/index.html#play.api.mvc.AbstractController

I honestly didn’t know they were the same site until I changed the number in 2.6 to 2.7 I discovered this while looking for API Documentation about the controllers. To my surprise the documentation is under MVC NOT CONTROLLERS. ME and my silly logical brain.

@AkashicSeer the change in the API documentation layout came about as a result of changes to the scaladoc tool between Scala 2.11 and 2.12. The Play 2.6 documentation was built with Scala 2.11, and with Play 2.7 it is built with 2.12.

I really like the 2.6 version better. Is there any way to view 2.7 with the 2.6 layout? Maybe I am weird because I like to sit there and read documentation to get an overall idea of where things are all together, I spent over an hour scrolling through looking at the 2.6 docs.

The search feature works nice in 2.7, I just like the fully expanded column in the 2.6. The content of the API documentation is nice and thorough. But for a while it was confusing because I would use google to look some things up, then links in the Overall documentation to view individual things, and it looked like two different docs until I looked at the URLS. Neither version of the documentation make it obvious which version you are viewing, so you have to look to the URL. I literally thought I was on two different websites.

Thanks to all the people involved with the API documentation.

For Play 2.7, you could locally build the documentation using Scala 2.11, but this option will disappear with the next Play release, which is dropping support for Scala 2.11. At the end of the day, Play is bound here by what scaladoc generates, so if you think the new generator is a step backward, it’s probably better to bring that up on the Scala Users forum (or contribute improvements to the tool).

Putting the Play version in the title and header would be a good improvement. Akka does this: https://doc.akka.io/api/akka/current/akka/actor/. Would you be able to raise an issue in https://github.com/playframework/playframework/issues?

I used Playframework as a hobby for a little application a while ago. I love Scala, it’s my favorite language but at work I use C#.

I find the documentation to be good in general, perhaps the search could be improved a little bit. Imo, the search drop-down popup is a bit weird - I am so used to search engines were I type something and press enter and I go to a results page. If I search Sec the pop-up comes back with about 4 results. I get the impression that it doesn’t find everything. If I come back to the search page I have to type something in the search box to make the popup appear again. It’s annoying.

Anyway, as a beginner I find working with Playframework harder than other web servers, particularly getting off the ground and running something simple that authenticates a user, connects to a database and returns some results. If I were to compare it with Tomcat or Weblogic which I worked with in the past, they are a breeze. Let’s take it by points:

  • authentication, authorization - it’s almost non-existent out-of-the-box - I am redirected to some third-party products which may or may not be maintained. This is a crucial piece of a web server right from the get go. It should have been done and solved by now - it can’t be left to third-party entities. I work in a windows environment and I need to authenticate against AD. I would have to spend probably days to figure out what to use and how to do it in play. Tomcat/Weblogic have AD plugins that can be configured and used as far as I know.
  • connection to a database - when I developed the app in Play, the server didn’t start if the database server was down. I had to modify the source code of the db module to get rid of this issue. Again, I had to spend time to read the code and understand what it does. Compare that to Weblogic or Tomcat where I configure a connection pool and everything was taken care of with all the parameters that one can think of to retry connections, close connections etc.
  • when I developed the app I bumped into some security filters - I wasn’t aware I had to implement them in the page - well, maybe it was a good thing. I read the docs and I did it.
  • programming wise, everything is harder in Play. I have to stop, take my time to read the examples, the documentation and understand what everything does and how things tie together. I am currently working with C# and Web Api 2.0. It is so simple in .net, that I had a shock when I tried to do the same thing with Play following the Play Rest Api example. Truly, I had a wtf moment.
  • another one that I was curious about was the ability to deploy in an exploded format. Sometimes let’s say I want just to modify a script file or some images and instead of deploying the whole thing again I want to be able to copy the new files (images). Is it possible?

Anyway, that’s my experience. Perhaps you should take it with a grain salt :-)

One other thing, I met a few folks at a scala course and they all seem to use http4s and the typelevel stack. I was surprised. That should pause you for some thoughts.

Cheers