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

Play Framework
1

Asking the general community here: how easy was it to get started with Play as a new user? How easy was it to get started with a new project, see routes, etc? What was the hardest part of getting started with Play?

Reason I ask is because there’s been a couple of examples of new users having a hard time:

and it’d be nice to get more feedback on this.

2 Likes
2

While I’m not a new user, I did do a migration for a 2.2.x project, migrating it to 2.6.x(2.5.x at first, then 2.6 came out while I was working on it).

I’d say the migrations were 90% useful. I was still stuck in certain situations and using the search was not always easy.

Doing this migration, I eventually came to the conclusion I’d have to read the entire thing front to back. Which I did. You’d think I’d remember a few pages off the top of my head, but I don’t.

Anyway, this approach was needed because the search sometimes didn’t take me to where I needed to go and also, most importantly, I just wasn’t aware of certain concepts. I didn’t know they existed, so I didn’t know the keywords to search for.

I stumbled onto certain solutions by simply checking every single page, one by one. So, the “next page” feature is absolutely useful.

While I think the documentation as it is now is fairly large and has a good number of examples, it’s easy to get lost and sometimes the search function doesn’t help much.

EDIT: Side note: is anyone maintaining the subreddit: https://www.reddit.com/r/play/ ?

The 2 newest posts are screenplays/theater pieces.

1 Like
3

Side note: is anyone maintaining the subreddit: Reddit - Dive into anything ?

I don’t know who they are, but here is the list of moderators: https://www.reddit.com/r/play/about/moderators. I reported the links as spam.

4

I am just an ordinary app developer to get things done. I am more like a commuter using a car to get to places than to get to know the innards of my car on weekends so that I can commute.

So for me, I started out in Java, and switching the main text with Java and Scala versions was not very intuitive. I tend to click the version on the right thinking that that would accomplish it, but that’s the API docs which of course is very frustrating. In fact, once you get stuck in Scala, the only way to fix that is to manually change the URL to… /Java/…

I both liked the Apple Developer site approach where I choose the language on top right somewhere, or in MSND where you can use different examples written in supported languages. But in our case, the whole text is language dependent, so the Apple approach is probably what I am looking for.

Also, I think we can facilitate the Scala adoptation from the Java camp whenever non-Java construct appears in the Scala documentation to explain a bit about what’s going on. More specifically, there are a lot of operators and overrides of them in Scala, which makes it very cryptic to read unless you already know what they are. I know you need to strike a balance.

1 Like
5

I’m a reasonably new user and I found the documentation was pretty good. I realise this is a trick question because I can always make a pull request, but here goes.

Things I found a little confusing when I first started:

  • Why multiple search results? The search bar provides a Java and a Scala result without showing which is which. It’s hard to tell if multiple pages are responsive to the search criteria and until you’ve used the site a bit you can’t tell if the top result is Java or Scala.
  • Which version am I reading? It would be helpful if the language and Play version was more constantly visible. I’ve been in 2.5-brain world a few times, carefully studied an example I found, then realised I might have wasted time on a 2.6 example.
  • Up-selling the latest version. I started out on a 2.5 project when 2.6 was new and all the while I wondered how badly I was shooting myself in the foot. I think it would be helpful if features that change or are deprecated for a future release are called out in the previous release’s documentation so readers can make trade-offs between expending effort using a deprecated or changing feature or making the leap to a new version of the framework. I know there are upgrade guides for 2.5 in the 2.6 documentation, but it would be nice to call out the pain points in the 2.5 documentation with links forward into the 2.6 documentation.
1 Like
6

I’m using play for over a year now, with Java, its good to start off with basics, well documented to get you started.

Once when you enter into an advance stage, where in you have to deal with streams, events & chunks, futures, examples and documentation become sparse. If the examples are found, they are of the older version.

Nice examples in this space, will eventually help people to acknowledge the benefits what play brings to the table.

Using play with Akka, examples on these are rare to find and as said previously the version are not relevant or recent.

7

Once when you enter into an advance stage, where in you have to deal with streams, events & chunks, futures, examples and documentation become sparse. If the examples are found, they are of the older version.

This is where the examples are supposed to pick up – they cover more complex topics where it’s not enough to show the text, you also have to show the idioms and see some running code.

They SHOULD be current to the Play version though.

8

Appreciate your response, for pointing out to the right link, where in we get into advance and complex constructs.

Apart from that, another area, where in we have got stuck is with migrating from one version to the next.
To illustrate precisely, we were initially using SSE using EventSource.Event construct of play 2.4,

EventSource eventSource = new EventSource() {
    @Override
    public void onConnected() {
        send(Event.event("hello"));
        send(Event.event("world"));
        ...
    }
};
return ok(eventSource);

The documentation when it comes to migration says, https://www.playframework.com/documentation/2.6.x/StreamsMigration25

To migrate EventSource.onConnected , EventSource.send , etc to a Source , implement org.reactivestreams.Publisher on the class and use Source.fromPublisher to create a source from the callbacks.

I’ve gleaned the web, what ever possible from my end, but could not find the right instructions to help me migrate to play2.5. Though found an example which has shows how to implement Publisher interface, but fell short on how to hook up onConnected event in 2.5.

Probably pointers on these, could help people who are migrating from one version to another.

9

My experience so far, coming from a Java background and also using Play with Java:

Getting started with your typical Hello World! style is simple, the documentation covers pretty much all the core concepts well, the way routes are defined makes sense. However, as soon as I start getting into using Play for real world scenarios, that is when things start to get “interesting”.

For example, configuring the application to be non-blocking for database access in Java with a blocking driver (e.g. JDBC). Since almost all apps will be talking to a DB in one way or another, I feel this part of documentation warrants its own section with in-depth, step by step documentation. While I am aware that there is documentation for this, I think it should be highlighted in a more prominent place in the documentation, since by default, the application will be blocking, and new users will incorrectly assume otherwise (I know I did). Furthermore, the linked documentation make me (as a new user) feel like there are many “assumed knowledge” about Akka and other things that Play uses under the hood, by only showing various code snippets and assumes I would know where to put it, and how to customize it to my needs, which I did not. The page does have links to further documentation about Akka, etc… but honestly, I just want to know what I need to do to make my Java application using Play talking to the database with a blocking driver.

Another area of pain is the default build tool, sbt. It is just hard to use, While the getting started sample project comes with a fully functional sample build.sbt file, as soon as I need to customize it for my specific build needs, it becomes very very hard for someone who does not know Scala. A lot of Google searches were required to find the solution, which usually ends up being cut & paste & pray. I know that sbt is technically not Play, but due to the dependency Play has on it, it makes the experience less than enjoyable. As an added “bonus”, sbt is often not supported for some of the Cloud devops services, so sometimes it ends up being a deal breaker for adopting Play in my experience.

Overall, I would say my experience is positive, but I think if we can have documentation that covers more “real world use cases” (especially for us Java folks), it will go from good to great!

4 Likes
10

Thank you for the great feedback everyone.

Yes, that is something we agree needs some work: have step-by-step guides that “glues” parts of the documentation from a use-case perspective. Thank your for the confirmation and good explanation too.

That is interesting. Could you point us to specific sections where you had that feeling?

Not sure if you are aware of it, but Gradle has Play support, although we don’t have detailed documentation on our side covering it.

Best.

11

That is interesting. Could you point us to specific sections where you had that feeling?

For example, I had no idea what a fork-join-executor is. And I think there is another option thread-pool-executor, which is the recommended option for blocking scenarios (e.g. JDBC).

Also, this is probably just an oversight, the documentation also has the below snippet about Akka threadpool configuration. That particular comment does not give me confidence in the documentation, especially as a new user who has no idea about Akka (kind of makes me feel it assumes I know enough about Akka to figure it out).

# @richdougherty: Not sure why this is set below the Akka
# default.
parallelism-max = 24

Not sure if you are aware of it, but Gradle has Play support2, although we don’t have detailed documentation on our side covering it.

Yes, in fact, I got in touch with the LinkedIn devops engineer who gave a talk about using it when I first heard about it on YouTube. Back then it was still in beta/incubation, but I will check it out again. If it is on-par in terms of feature and support as sbt, then it is probably good enough.

Just as a side comment, Maven support would also be nice. I know there is a Maven plugin that supports Play, but when it is not “officially supported”, makes it harder to present it. But I digress as it is a bit off topic.

1 Like
12

I was reminded of a bit of research I did once about threadpools.

Even after reading and watching all these links, I’m still a bit uncertain about executors and thread pools, expect for that one formula about how many threads you should give to your database connections

The links I read back then:

On threads being created: https://groups.google.com/forum/#!topic/play-framework/mrx2CUR8U2A

On highly synchronous thread pools: https://www.playframework.com/documentation/2.6.x/ThreadPools#highly-synchronous

Play example on how to properly set amount of threads: https://github.com/playframework/play-java-ebean-example/blob/2.6.x/conf/application.conf

On thread pool sizes(Really important, read and watch it all): https://github.com/brettwooldridge/HikariCP/wiki/About-Pool-Sizing

What are spindles(hikaricp document references them): https://blogs.technet.microsoft.com/pkcrm/2009/04/25/think-spindles-not-space/

13

The Play documentation itself is really lax at explaining the underlying architecture.

There’s been blog posts and presentations and white papers about how threads and execution contexts and so on all work in Play:

But it doesn’t really cover it in the docs itself.

14

When I first came to play, I was new to MVC and learning Java (as well as C#). It was after the switch to play 2 and the original creator of play Guillaume Bort created a tutorial called Zentasks. Other than the fact he used coffeescript and Backbone.js in the tutorial, I thought it was great. I later on did the .net MVC movie tutorial in C# which was also great.

I think a tutorial like this should be made with Scala and Play. By including all these things together, it really helps someone learn the framework in the context of the way it was meant to be used. I think that it’s especially important for the Scala community that Play to do this because if you think of it the first thing a person is going to do if they try to learn Scala is create a simple hello world application in the console and then next try to do some simple crud web application. They will google and see Play is the leading web framework like ROR, Django and .net MVC. Documentation is ok, but it’s like jigsaw puzzle you have to put together yourself without the picture on the box. I would be nice to have that picture and a bit of guidance to help you along. Also even considering that the person is not only new to Scala, Java and Play, but may even be new to the MVC pattern.

Also it would be great to have the import statements in the examples given in the documentation.

1 Like
15

I am not a new user of play. I am currently heavily using the 2.6.x migration guide, and I must admit it is very detailed. I almost find solutions to 90% of the issues migrating from 2.3.x to 2.6.x searching the guide.
Though I hate the breaking changes from Promise to CompletableFuture and many other API :slight_smile:, the guide has been a friend along the way. Great work. :+1:

1 Like
16

Two difficult things for me to start using Playframework:

Bare controller isn’t useful

For example, it doesn’t support authenticating user. What I do in my application is that I’d make BaseController that offers:

def async[R](
  bodyParser: BodyParser[R]
)(
  fn: Context[R] => Future[Result]
): Action[R] = Action.async(bodyParser) { implicit request =>
  // get user from cookies
 // instantiate Context (which contains info about authenticated user
  fn(context)
}

Then, in my normal controller, I’d would async instead of using Action.async. Context will be injected to everywhere because the info about logged-in user is often needed everywhere.

This is heavyweight, and I imagine it’s difficult for a new user to solve a problem like this because it’s an architecture problem and requires a bunch of boilerplate.

Rails doesn’t seem to have this problem because we can authenticate user and store it in @loggedInUser. We don’t have to pass Context around like what I do in Playframework.

Writing tests

This is also very heavyweight. I had to make things like:

  lazy val app = new GuiceApplicationBuilder()
    .configure(Configuration.from(generateAppConfig))
    .in(Mode.Test)
    .build()

Reset database before every and run evolution with app.injector.instanceOf[EvolutionsApi].applyFor("default").

For a selenium test, I’d need to start the Play server with:

lazy val testServer = TestServer(
    port = BaseSpec.PORT,
    application = BaseSpec.app)
testServer.start()

These things seem undocumented. I imagine it would be super hard for new users to know these things (e.g. running evolution through code).

For tests to look nice, it requires a bunch of boilerplate as well.

Rails doesn’t require me to do all these things. We just install a gem, and that’s it. I think it’s the power of Ruby’s monkey patching.

The best thing about Playframework and Scala

I feel we should advertise this more. I use Playframework and Scala because of (1) type safety and (2) brevity (well, more concise than other typed languages and other frameworks).

For Rails, it becomes exponentially more difficult to maintain as the codebase grows. Rails and Ruby is very punishing if we delay upgrading gems or Rails’ version itself.

I used to maintain a 5-year old Rails, which was still on the version 3. It was a nightmare. Couldn’t upgrade a gem because it conflicted with another gem. Couldn’t find good documentation for a certain gem because the gem was old.

17

Thanks for the feedback. For the newere guides (Migration26), if you find something missing, please consider opening an issue or submitting a pull request. :-)

Part of what makes those guides well detailed is the great contributions we get from community.

Best.

18

I think you want Action Builders:

:slight_smile:

For the test documentation, I agree the APIs can improve, and docs too. Have you seen the docs here?

Were they useful to you? How can we improve them?

Best.

1 Like
19

Thanks for the recommendation. I just tried it on our new system. It’s exactly what I need, and it’s much cleaner.

1 Like
20

The main issue I had as new user is the link management on https://www.playframework.com/

I have a french browser. So when I choose to get latest documentation, I use the “Documentation 2.7.0” button which opens French doc in 2.4.x and no information about 2.7.x !

Ok, let’s continue. I switch to english (I know the issue now). A small banner tells me I’m not consulting the latest doc. " You are viewing the documentation for the 2.4.x release series. The latest stable release series is 2.7.x". But the link under “2.7.x” is https://www.playframework.com/documentation/en-US/2.7.x/Home which goes nowhere. The correct one is https://www.playframework.com/documentation/switch/2.7.x/Home

Aa a new user, it was easiest to navigate in the doc using Google.

Finally, the new 2.7.0 API doc is pretty as scala-lang but search bar doesn’t work :-(

Despite of this issues, I could find useful information browsing this doc :-)
I’d say 80-90% of my needs.