Getting starter experience improvements #8385

marcospereira · 2018-04-27T23:13:09Z

Purpose

Lots of improvements to Play getting started experience. This is the result of work with @rstento and replaces #8295.

References

gmethvin · 2018-04-29T01:36:13Z

documentation/manual/gettingStarted/HelloWorldTutorial.md

+
+Play APIs are available in both Java and Scala. The Framework uses [Akka](https://akka.io) and [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html) under the hood. This endows Play applications with a stateless, non-blocking, event-driven architecture that provides horizontal and vertical scalability and uses resources more efficiently. Play projects contain Scala components, but you do not need to learn Scala to use Play successfully if you are a Java developer.
+
+The following describe just a few of the reasons why developers enjoy using Play framework:


We could say "Here are just a few of the reasons developers love using Play Framework:"

gmethvin · 2018-04-29T01:39:45Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+To define a route for the new Hello page:
+
+Open the `conf/routes` file and aFdd the following line:


s/aFdd/add/

gmethvin · 2018-04-29T01:50:37Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+Open the `conf/routes` file and aFdd the following line:
+
+@[hello-world-hello-route](code/commonguide/routes)


Since the routes generation is a big part of the "magic" that Play provides, I think it'd be helpful to explain what it's actually doing. In other words, something like:

"When you add a route to the routes file, Play's routes compiler will automatically generate a router class that calls an instance of your controller. For more information see the routing documentation. The controller instances are created using dependency injection."

gmethvin · 2018-04-29T02:16:33Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+This was just a simple example to get you started. Next, pick one that demonstrates functionality of interest to you. The examples you can download cover the following topics:
+
+### Java


I'd prefer if we can example service API directly to render the examples, so we don't have to manually update with new versions/examples.

I thought about that too, but it would be easier to keep this page on playframework.com. However, if we are linking to another page, why not to link directly to Tech Hub? So I understand this list as a hand pick of the examples.

Maybe we should not include all of them here?

@rstento, what do you think?

Could we update the example code server so it can render an iframe listing all templates which we can just embed here?

@richdougherty nice idea.

But I'm not sure this is something that is part of the Tech Hub, maybe we are the only "customer" that needs it? Anyway, we can always do our own page that is embeddable. ;-)

I agree that having something that refreshes itself is good. However, I found the "laundry" list of Play examples on Tech Hub daunting and difficult to sort through. I have a request in to the tooling team to implement a filter that allows you to view only Java or only Scala examples, but it is a WIP. I think for a new user, providing a brief explanation of what the examples are so they know where to go next is important. It that can be done, either by modifying the cards in Tech Hub, or pulling in the info in a different way, I'm all for it.

I have a request in to the tooling team to implement a filter that allows you to view only Java or only Scala examples, but it is a WIP.

I think it is possible to do it on our side too. But agree that this should be something Tech Hub provides.

I think for a new user, providing a brief explanation of what the examples are so they know where to go next is important. It that can be done, either by modifying the cards in Tech Hub, or pulling in the info in a different way, I'm all for it.

We already have some explanation, but it is not that brief. It is another piece of data that needs to be present at the Tech Hub service I think so we can manage all the data related to the example in a single place.

gmethvin · 2018-04-29T02:37:27Z

documentation/manual/gettingStarted/Introduction.md

+
+Play’s lightweight, stateless, web-friendly architecture uses Akka and Akka Streams under the covers to provide predictable and minimal resource consumption (CPU, memory, threads). Thanks to its reactive model, applications scale naturally--both horizontally and vertically. See [Elasticity](https://developer.lightbend.com/elastic-scaling/) and [Efficient Resource Usage](https://developer.lightbend.com/efficient-resource-usage/) for more information.
+
+Play is non-opinionated about database access, and integrates with many object relational mapping (ORM) layers.  It supports [[Anorm]], [[Ebean|PlayEbean]], [[Slick|PlaySlick]], and [[JPA|JavaJPA]], out-of-the-box but many customers use NoSQL or other ORMs.


I'd use spaces for "out of the box" with no comma before. Also "users" instead of "customers" (it's an open source framework, not a company). e.g. "It integrates with Anorm, Ebean, Slick and JPA out of the box, but many users use NoSQL or other ORMs with Play.

gmethvin · 2018-04-29T02:51:45Z

documentation/manual/gettingStarted/Requirements.md

+
+Play example projects available from [Lightbend Tech Hub](https://developer.lightbend.com/start/?group=play) automatically download dependencies and have `./sbt` and `sbt.bat` launchers for Unix and Windows environments, respectively. You do not have to install sbt to run them.
+
+If you are ready to start your own project and want to use sbt, refer to the [sbt download page](https://www.scala-sbt.org/download.html) to install the sbt launcher on your system. See [sbt documentation](http://www.scala-sbt.org/release/docs/Setup-Notes.html) for details about how to setup sbt. We recommend that you use the latest version of sbt. With sbt installed, you can use our [giter8](http://www.foundweekends.org/giter8/) templates for Java or Scala to [[create a new project with a single command|NewApplication]].


What does installing the sbt launcher have to do with starting a new project? In other words, what is the downside of using the ./sbt script?

This can be reworded, but the idea is that "with sbt installed, you can use our giter8 templates for Java and Scala to create a new project with a single command. Maybe this should be at the start of the paragraph instead of the end. What do you think about this:

But if you want to use sbt to create your project, you need to install the sbt launcher on your system. With sbt installed, you can use our gitter8 template for Java or Scala to create a new project with a single command, using sbt new. Refer to the sbt download page to install the sbt launcher on your system and sbt documentation for details about how to setup it.

@rstento what do you think?

Nice rewording!

gmethvin · 2018-04-29T02:52:44Z

documentation/manual/gettingStarted/code/scalaguide/hello/HelloController.scala

+  }
+  //#hello-world-hello-action
+
+  /*


You probably want to uncomment and move these to a separate file.

Good idea.

I can do that to the one that compiles, but not to the one that does not.

gmethvin · 2018-04-29T02:55:26Z

documentation/manual/gettingStarted/Tutorials.md

-This is an example template showing compile time dependency injection using [Macwire](https://github.com/adamw/macwire).
-
-* [playframework/play-macwire-di](https://github.com/playframework/play-macwire-di)
+Play uses [Lightbend Tech Hub](https://developer.lightbend.com/start/?group=play) to publish tutorials that cover a huge number of cases. There you can find projects in Java, Scala and for multiple versions of Play.  


Instead this should be "The Play team uses Lightbend Tech Hub.."

By the way, this was another place where the examples list was duplicated, but with additional details and categorization. I decide to remove it from here in favor of linking to Tech Hub. As I said before, an alternative is to have these links listed in a page on playframework.com.

@rstento what do you think?

richdougherty · 2018-05-04T06:24:40Z

documentation/manual/gettingStarted/HelloWorldTutorial.md

+
+## Introduction to Play
+
+As illustrated below, Play is a full-stack framework with all of the components you need to build a Web Application or a REST service, including: an integrated HTTP server, form handling, Cross-Site Request Forgery (CSRF) protection, a powerful routing mechanism, I18n support, and more. Play integrates with many object relational mapping (ORM) layers. It supports [[Anorm]], [[Ebean|JavaEbean]], [[Slick|PlaySlick]], and [[JPA|JavaJPA]] out-of-the-box, but many customers use NoSQL or REST layers and other ORMs.


REST layers <-- doesn't seem to fit into this list of ORMs and NoSQL?

... but many customers use NoSQL or REST layers and other ORMs.

Rewrite to:

but many customers use NoSQL, other ORMs or even access data from a REST service.

WDYT?

Yes, I like the rewrite ...but many customers use NoSQL, other ORMs or even access data from a REST service.

richdougherty · 2018-05-04T06:25:58Z

documentation/manual/gettingStarted/HelloWorldTutorial.md

+
+[[images/play-stack.png]]
+
+Play APIs are available in both Java and Scala. The Framework uses [Akka](https://akka.io) and [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html) under the hood. This endows Play applications with a stateless, non-blocking, event-driven architecture that provides horizontal and vertical scalability and uses resources more efficiently. Play projects contain Scala components, but you do not need to learn Scala to use Play successfully if you are a Java developer.


Play projects contain Scala components, but you do not need to learn Scala ...
-->
Play projects contain Scala components, but because Play has a Java API, you do not need to learn Scala ...

richdougherty · 2018-05-04T06:26:29Z

documentation/manual/gettingStarted/HelloWorldTutorial.md

+Here are just a few of the reasons developers love using Play Framework:
+
+- Its Model-View-Controller (MVC) architecture is familiar and easy to learn.
+- Direct support of common web development tasks and hot reloading save precious development time.


save -> saves

richdougherty · 2018-05-04T06:29:39Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+1. Define a route
+1. Customize the greeting
+
+## Create the Hello World page


Not sure, but perhaps put a number in front of this heading and the following headings so that they match the numbering in the list above?

documentation/manual/gettingStarted/ImplementingHelloWorld.md

richdougherty · 2018-05-04T06:37:08Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+[[images/hello-page.png]]
+
+## Customize the greeting


Perhaps this could be in a section about "Automatic reloading and display of errors" or something like that.

richdougherty · 2018-05-04T06:37:33Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+: 
+@[hello-world-hello-error-action](code/scalaguide/hello/HelloController.scala)
+
+In the `conf/routes` file, add a (name: String) parameter at the end of the `hello`:


Add backticks around (name: String).

richdougherty · 2018-05-04T06:39:09Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+In the browser, enter the following URL and pass in any name as a query parameter to the hello method: <http://localhost:9000/hello?name=MyName>. Play responds with a helpful compilation error that lets you know that the render method in the return value requires a typed parameter:
+
+[[images/hello-error.png]]


Really nice to demo this!

richdougherty · 2018-05-04T06:40:44Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+This was just a simple example to get you started. Next, pick one that demonstrates functionality of interest to you. The examples you can download cover the following topics:
+
+### Java


Could we update the example code server so it can render an iframe listing all templates which we can just embed here?

documentation/manual/gettingStarted/ImplementingHelloWorld.md

richdougherty · 2018-05-06T23:49:59Z

documentation/manual/gettingStarted/Introduction.md

+
+Play is a high-productivity Java and Scala web application framework that integrates components and APIs for modern web application development. Play was developed by web developers for web application development.
+
+You will find Play's Model-View-Controller (MVC) architecture familiar and easy to learn. Play provides concise and functional programming patterns. And, the large community developing Play applications provides an excellent resource for getting your questions answered.


Remove , from And,.

richdougherty · 2018-05-06T23:56:44Z

documentation/manual/gettingStarted/NewApplication.md

 # Creating a new application

-## Using Play Starter Projects
+To learn about Play hands-on, try the examples as described below, they contain everything you need to build and run them. If you have sbt installed, you can create a Play  project with a single command, using our giter8 Java or Scala  template. The templates set up the project structure and dev environment for you. You can also easily integrate Play projects into your favorite IDE.


Could sbt installed link to the sbt page or sbt installation page?

documentation/manual/gettingStarted/NewApplication.md

richdougherty · 2018-05-07T00:18:14Z

documentation/manual/gettingStarted/NewApplication.md

+## Using a project template

-> **Note**: If running Windows, you may need to run sbt using `sbt.bat` instead of `sbt`. This documentation assumes the command is `sbt`.
+If you already have sbt installed, you can use a giter8 template, similar to a Maven archetype, to create a new Play project. This gives you the advantage of setting up your project folders, build structure, and development environment--all with one command.


Again link to sbt from the sbt installed words?

richdougherty · 2018-05-07T00:19:00Z

documentation/manual/gettingStarted/NewApplication.md


-You can also [create your own giter8 seeds](http://www.foundweekends.org/giter8/usage.html) and based off this one by forking from the <https://github.com/playframework/play-java-seed.g8> or <https://github.com/playframework/play-scala-seed.g8> GitHub projects.
+1. Enter `sbt run` to download dependencies and start the system.
+1. In a browser, enter <http://localhost:9000> to view the welcome page.


As mentioned earlier, maybe make this an so the user can click it? I suggest using a fixed target too so that it always opens in a specific tab.

richdougherty · 2018-05-07T00:36:25Z

documentation/manual/gettingStarted/PlayConsole.md

+## Development mode

-## Running the server in development mode
+In this mode, sbt launches Play with the auto-reload feature enabled. For each request, Play will watch your project files and recompile required sources when they change. If needed the application will restart automatically.


This seems ambiguous about whether Play will recompile eagerly or only when a request is made. Maybe something like the following?

When you make a request, Play will automatically recompile and restart your server if any files have changed.

documentation/manual/gettingStarted/PlayConsole.md

richdougherty · 2018-05-07T01:13:50Z

documentation/manual/gettingStarted/Requirements.md

+<!--- Copyright (C) 2009-2018 Lightbend Inc. <https://www.lightbend.com> -->
+
+# Play Requirements
+Play is a series of libraries available in Maven Repository so that you can use any Java or Scala build tool to build a Play project. However, much of the development experience Play is known for (routes, templates compilation and auto-reloading) is provided by sbt or Gradle.


A Play application only needs to include the Play JAR files to run properly. These JAR files are published to the Maven Repository so you can use any Java or Scala build tool to build a Play project. However, Play provides an enhanced development experience (support for routes, templates compilation and auto-reloading) when using the sbt or Gradle build tools.

documentation/manual/gettingStarted/Requirements.md

rstento · 2018-05-14T16:05:48Z

documentation/manual/gettingStarted/HelloWorldTutorial.md

+
+## Introduction to Play
+
+As illustrated below, Play is a full-stack framework with all of the components you need to build a Web Application or a REST service, including: an integrated HTTP server, form handling, Cross-Site Request Forgery (CSRF) protection, a powerful routing mechanism, I18n support, and more. Play integrates with many object relational mapping (ORM) layers. It supports [[Anorm]], [[Ebean|JavaEbean]], [[Slick|PlaySlick]], and [[JPA|JavaJPA]] out-of-the-box, but many customers use NoSQL or REST layers and other ORMs.


Yes, I like the rewrite ...but many customers use NoSQL, other ORMs or even access data from a REST service.

documentation/manual/gettingStarted/ImplementingHelloWorld.md

rstento · 2018-05-14T16:08:34Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+1. Define a route
+1. Customize the greeting
+
+## Create the Hello World page


rstento · 2018-05-14T16:11:30Z

documentation/manual/gettingStarted/ImplementingHelloWorld.md

+
+This was just a simple example to get you started. Next, pick one that demonstrates functionality of interest to you. The examples you can download cover the following topics:
+
+### Java


I agree that having something that refreshes itself is good. However, I found the "laundry" list of Play examples on Tech Hub daunting and difficult to sort through. I have a request in to the tooling team to implement a filter that allows you to view only Java or only Scala examples, but it is a WIP. I think for a new user, providing a brief explanation of what the examples are so they know where to go next is important. It that can be done, either by modifying the cards in Tech Hub, or pulling in the info in a different way, I'm all for it.

documentation/manual/gettingStarted/ImplementingHelloWorld.md

documentation/manual/gettingStarted/NewApplication.md

documentation/manual/gettingStarted/PlayConsole.md

rstento · 2018-05-14T16:21:54Z

documentation/manual/gettingStarted/Requirements.md

+
+Play example projects available from [Lightbend Tech Hub](https://developer.lightbend.com/start/?group=play) automatically download dependencies and have `./sbt` and `sbt.bat` launchers for Unix and Windows environments, respectively. You do not have to install sbt to run them.
+
+If you are ready to start your own project and want to use sbt, refer to the [sbt download page](https://www.scala-sbt.org/download.html) to install the sbt launcher on your system. See [sbt documentation](http://www.scala-sbt.org/release/docs/Setup-Notes.html) for details about how to setup sbt. We recommend that you use the latest version of sbt. With sbt installed, you can use our [giter8](http://www.foundweekends.org/giter8/) templates for Java or Scala to [[create a new project with a single command|NewApplication]].


Nice rewording!

documentation/manual/gettingStarted/Requirements.md

marcospereira · 2018-05-15T13:15:01Z

@rstento, @richdougherty, and @gmethvin.

I've made most of the changes suggested, so this should be good to go.

The sample projects listing needs some additional work that will happen in another project, so I would say to keep the list as is here and later add new features to playframework.com or the Tech Hub.

WDYT?

rstento · 2018-05-15T14:56:21Z

@marcospereira, one thing to keep in mind is that the Hello World tutorial sample apps need to be merged at the same time as the documentation, to replace play-java-starter and play-scala-starter. Do you want me to create those PRs, or have you done it already?

On Tue, May 15, 2018 at 8:15 AM Marcos Pereira ***@***.***> wrote: @rstento <https://github.com/rstento>, @richdougherty <https://github.com/richdougherty>, and @gmethvin <https://github.com/gmethvin>. I've made most of the changes suggested, so this should be good to go. The sample projects listing needs some additional work that will happen in another project, so I would say to keep the list as is here and later add new features to playframework.com or the Tech Hub. WDYT? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#8385 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AV1De556mcpmHFuNXTDyY9jcKoOaAzB7ks5tytTwgaJpZM4TrH9V> .

-- Ruth Stento User Experience Lead Lightbend 512-818-6459 <http://lightbend.com>

TimMoore · 2018-08-02T09:16:34Z

@marcospereira @richdougherty could you have another look at this?

rstento · 2018-09-19T16:48:12Z

documentation/manual/tutorial/HelloWorldTutorial.md

+    1. [Play Scala Starter Example](https://developer.lightbend.com/start/?group=play&project=play-scala-starter-example)
+1. Unzip and run the example following the steps in the `README.md` file.
+
+## Introduction to Play


@marcospereira, should we take this section out, since it is a duplicate of what is in the example? Or could it be moved elsewhere?

rstento · 2018-09-19T16:49:42Z

documentation/manual/tutorial/ImplementingHelloWorld.md

@@ -0,0 +1,114 @@
+<!--- Copyright (C) 2009-2018 Lightbend Inc. <https://www.lightbend.com> -->
+
+# Implementing Hello World


I definitely think we should remove these instructions since they now duplicate those in the Hello World self-contained examples for Java and Scala. @marcospereira WDYT?

I'm okay with that if we publish the examples to somewhere that is easier to find and consume. The current state is that search engines don't index them and you need to create/run a project to read them.

I like these instructions. In the PlayAppOverview (just before this one) you see code that's in the app already. This page is a call to action with enough hand-holding that if something breaks it should be immediate to spot the error.

To me, the PlayAppOverview is a canary feature: if you checkout the code and the canary feature doesn't work, there's definitely something wrong. If the canary works, move forward and add a new route/controller/page yourself and, If something breaks, well, check back with the canary.

rstento · 2018-09-19T16:50:13Z

documentation/manual/tutorial/PlayApplicationOverview.md

@@ -0,0 +1,51 @@
+<!--- Copyright (C) 2009-2018 Lightbend Inc. <https://www.lightbend.com> -->
+
+# Play Application Overview


@marcospereira same comment here, this page can be removed.

rstento · 2018-09-19T22:00:54Z

Hmm, now you are making me think. Which content specifically do you think should be indexed by search engines? Ruth Stento User Experience Lead Lightbend <https://www.reactivesummit.org/registration?utm_source=email&utm_medium=email-signature&utm_campaign=EVT-2018-OCT-Reactive-Summit-Montreal&utm_term=none&utm_content=none> 512-696-1448 <http://lightbend.com>

…

On Wed, Sep 19, 2018 at 2:39 PM Marcos Pereira ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In documentation/manual/tutorial/ImplementingHelloWorld.md <#8385 (comment)> : > @@ -0,0 +1,114 @@ + + +# Implementing Hello World I'm okay with that if we publish the examples to somewhere that is easier to find and consume. The current state is that search engines don't index them and you need to create/run a project to read them. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#8385 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AV1DexiLXLPqHXZmBVmOQDiboLhwLeTjks5ucp2NgaJpZM4TrH9V> .

marcospereira · 2018-09-19T22:42:43Z

Which content specifically do you think should be indexed by search engines?

The complete Hello World tutorial. It should be possible for me to google for "playframework hello world" and reach the proper documentation page.

ignasi35

Left a handful of comments:

some cosmetic issue wrt links dendered twice (affects few places, I haven't tagged all of them)
coherence around route/controller/view order (some sections use route/controller/view and some sections use controller/route/view... a bit confusing)
minor cosmetic or typos.

ignasi35 · 2018-09-20T09:50:48Z

documentation/manual/hacking/Translations.md

 Another very helpful tool provided by Play is a translation report, which shows which files have not been translated, and also tries to detect issues, for example, if the translation introduces new files, or if the translation is missing code samples.  This can particularly help when translating a new version of the documentation, since the addition or removal of code samples will often be a good signal that something has changed.

-To view the translation report, run the documentation server (like normal), and then visit <http://localhost:9000/@report> in your browser.  By default it will serve a cached version of the report if it has been generated in the past, you can rerun the report by clicking the rerun report link.
+To view the translation report, run the documentation server (like normal), and then visit <a target="play-docs" href="http://localhost:9000/@report">http://localhost:9000/@report</a> in your browser.  By default it will serve a cached version of the report if it has been generated in the past, you can rerun the report by clicking the rerun report link.


This change renders wrong (at least locally). What seems to happen is that two <a> objects are created:

(See the two icons and also the two <a> elements in the inspector).

This problem happens in fe places in this PR.

Done here and at other places.

ignasi35 · 2018-09-20T09:55:17Z

documentation/manual/tutorial/HelloWorldTutorial.md

+  - Provides type safety
+  - Is compiled so that errors display in the browser
+
+To learn more about Play's benefits, visit the [Play website](https://www.playframework.com). Now, let's dive into what a Play application looks like.


I don't think this last line isn't necessary. Readers are on the play site already. :)

Yeah, pointing to Introduction and Philosophy pages make more sense.

ignasi35 · 2018-09-20T09:57:01Z

documentation/manual/tutorial/PlayApplicationOverview.md

+
+1. The browser requests the root `/` URI from the HTTP server using the `GET` method.
+1. The Play internal HTTP Server receives the request.
+1. Play resolves the request using the routes file, which maps URIs to controller action methods.


routes should be back-ticked:

1. Play resolves the request using the `routes` file, which maps URIs to controller action methods.

ignasi35 · 2018-09-20T09:57:48Z

documentation/manual/tutorial/PlayApplicationOverview.md

+1. The browser requests the root `/` URI from the HTTP server using the `GET` method.
+1. The Play internal HTTP Server receives the request.
+1. Play resolves the request using the routes file, which maps URIs to controller action methods.
+1. The action method renders the `index` page, using Twirl templates.


optionally, we could link "Twirl" to the twirl docs (not sure if you left the link out to avoid making too much noise)

To avoid the noise of linking Java & Scala versions here.

ignasi35 · 2018-09-20T09:58:55Z

documentation/manual/tutorial/PlayApplicationOverview.md

+Next, let's look at the tutorial project to locate the implementation for:
+
+1. The controller action method that defines how to handle a request to the root URI.
+1. The routes file that maps the request to the controller method.


backticks for routes

I think these 3 bullet points should be reordered.

In previous paragraphs, the request handling is presented as:

read routes

locate a controller

render a view

I think the files inspected here should follow the same logical order: present routes first always.

Good one. Done.

ignasi35 · 2018-09-20T11:54:06Z

documentation/manual/tutorial/PlayApplicationOverview.md

+1. The `app` subdirectory contains directories for `controllers` and `views`, which will be familiar to those experienced with the Model View Controller (MVC) architecture. Since this simple project does not need an external data repository, it does not contain a `models` directory, but this is where you would add it.
+1. The `public` subdirectory contains directories for `images`, `javascripts`, and `stylesheets`.
+1. The `conf` directory contains application configuration. For details on the rest of the project's structure see [[Anatomy of a Play Application|Anatomy]].
+


I think the two paragraphs above could be move to the end of this section. With that changed the whole Explore the project would look like this:

- in `pathX` there's router, it looks like this (show snipet) - in `pathY` there's the controller, it looks like this (show snipet) - in `pathZ` there's the twirl template,... Use a file browser to navigate the rest of the folder which include `app`, `models`, `public`, `conf`, ... (see Anatomy of a Play App). -- END OF SECTION --

So the section goes from the relevant meat of a simple router/controller/twirl to a more general overview.

Well, this is one these points where I'm always in doubt how much instructions we should give. Like, should we expect that developers know how to navigate through files and folders?

@rstento, what do you think?

ignasi35 · 2018-09-20T11:58:35Z

documentation/manual/tutorial/ImplementingHelloWorld.md

@@ -0,0 +1,114 @@
+<!--- Copyright (C) 2009-2018 Lightbend Inc. <https://www.lightbend.com> -->
+
+# Implementing Hello World


I like these instructions. In the PlayAppOverview (just before this one) you see code that's in the app already. This page is a call to action with enough hand-holding that if something breaks it should be immediate to spot the error.

To me, the PlayAppOverview is a canary feature: if you checkout the code and the canary feature doesn't work, there's definitely something wrong. If the canary works, move forward and add a new route/controller/page yourself and, If something breaks, well, check back with the canary.

ignasi35 · 2018-09-20T12:02:16Z

documentation/manual/gettingStarted/IDE.md

 Check the project's structure, make sure all necessary dependencies are downloaded. You can use code assistance, navigation and on-the-fly code analysis features.

-You can run the created application and view the result in the default browser `http://localhost:9000`. To run a Play application:
+You can run the created application and view the result in the default browser <a target="play-docs" href="http://localhost:9000">http://localhost:9000</a>. To run a Play application:


Here's another case. (not tagging all of them, though)

All fixed. :-)

ignasi35 · 2018-09-20T12:09:07Z

documentation/manual/gettingStarted/NewApplication.md

 # Creating a new application

-## Using Play Starter Projects
+To learn about Play hands-on, try the examples as described below, they contain everything you need to build and run them. If you have [sbt installed](https://www.scala-sbt.org/1.x/docs/Setup.html), you can create a Play  project with a single command, using our giter8 Java or Scala  template. The templates set up the project structure and dev environment for you. You can also easily integrate Play projects into your favorite IDE.


I always find very hard to spot when a tutorial presents two exclusive alternatives. This page has two sections and it's hard for me to understand I need to decide for one of them and will be able to ignore the other.

Is it just me?

It is not just you. We should later find a better way to explain seeds vs starter projects.

documentation/manual/gettingStarted/PlayConsole.md

marcospereira · 2018-09-20T17:32:29Z

@ignasi35 done for most of the suggestions.

ignasi35 · 2018-09-21T10:05:15Z

documentation/manual/tutorial/HelloWorldTutorial.md

  - Is compiled so that errors display in the browser

-To learn more about Play's benefits, visit the [Play website](https://www.playframework.com). Now, let's dive into what a Play application looks like.
+To learn more about Play's benefits, see Play's [[Introduction]] and [[Philosophy]]. Now, let's dive into what a Play application looks like.


ignasi35 · 2018-09-21T10:07:37Z

LGTM. Merge at will :P (fix conflicts, coordinate with other PR merges...)

dwijnand · 2018-09-26T16:01:54Z

@marcospereira Could you summarise what's blocking this from being merged, please?

Looks like Rich's review comments have been addressed

Backports #8385.

marcospereira requested review from gmethvin, richdougherty and wsargent April 27, 2018 23:13

gmethvin reviewed Apr 29, 2018

View reviewed changes

richdougherty suggested changes May 4, 2018

View reviewed changes

richdougherty previously requested changes May 7, 2018

View reviewed changes

rstento approved these changes May 14, 2018

View reviewed changes

rstento reviewed Sep 19, 2018

View reviewed changes

ignasi35 suggested changes Sep 20, 2018

View reviewed changes

ignasi35 reviewed Sep 21, 2018

View reviewed changes

ignasi35 approved these changes Sep 21, 2018

View reviewed changes

marcospereira added 10 commits September 21, 2018 17:32

Remove unused images

0e4848c

Moving "Installing" to "Requirements"

4fa6071

Revamping the getting started experience

7602c1b

Fix validateDocs

b6536b8

Fixes/improvements after review

28c731a

Move views and route files

d24236e

Compile getting started code samples

eda3307

Update missing copyright notices

c4e094e

Add missing copyright headers

e3e111f

Check copyright header for markdown docs

18b039f

marcospereira added 8 commits September 21, 2018 17:32

Minor corrections and improvements after review

a64912e

Add target to localhost links

3a01da2

Some rewording

799ef20

Adding numbers to tutorial sections

cc48b63

Small reorganization of tutorial docs

db900a5

Fix test-docs build

cd829a0

Add missing headers

ae659e6

Fix issues suggested by Ignasi

88ad126

dwijnand added the status:to-review label Sep 26, 2018

dwijnand removed the request for review from wsargent September 27, 2018 13:21

dwijnand merged commit 85936b7 into playframework:master Sep 27, 2018

marcospereira deleted the getting-starter-experience-improvements branch September 27, 2018 21:03

marcospereira mentioned this pull request Oct 1, 2018

[2.6.x]: Getting started experience improvements #8645

Merged

ignasi35 pushed a commit that referenced this pull request Oct 2, 2018

[2.6.x]: Getting started experience improvements (#8645)

71083d6

Backports #8385.


		Play APIs are available in both Java and Scala. The Framework uses [Akka](https://akka.io) and [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html) under the hood. This endows Play applications with a stateless, non-blocking, event-driven architecture that provides horizontal and vertical scalability and uses resources more efficiently. Play projects contain Scala components, but you do not need to learn Scala to use Play successfully if you are a Java developer.

		The following describe just a few of the reasons why developers enjoy using Play framework:


		To define a route for the new Hello page:

		Open the `conf/routes` file and aFdd the following line:


		Open the `conf/routes` file and aFdd the following line:

		@[hello-world-hello-route](code/commonguide/routes)


		This was just a simple example to get you started. Next, pick one that demonstrates functionality of interest to you. The examples you can download cover the following topics:

		### Java


		Play’s lightweight, stateless, web-friendly architecture uses Akka and Akka Streams under the covers to provide predictable and minimal resource consumption (CPU, memory, threads). Thanks to its reactive model, applications scale naturally--both horizontally and vertically. See [Elasticity](https://developer.lightbend.com/elastic-scaling/) and [Efficient Resource Usage](https://developer.lightbend.com/efficient-resource-usage/) for more information.

		Play is non-opinionated about database access, and integrates with many object relational mapping (ORM) layers. It supports [[Anorm]], [[Ebean\|PlayEbean]], [[Slick\|PlaySlick]], and [[JPA\|JavaJPA]], out-of-the-box but many customers use NoSQL or other ORMs.


		Play example projects available from [Lightbend Tech Hub](https://developer.lightbend.com/start/?group=play) automatically download dependencies and have `./sbt` and `sbt.bat` launchers for Unix and Windows environments, respectively. You do not have to install sbt to run them.

		If you are ready to start your own project and want to use sbt, refer to the [sbt download page](https://www.scala-sbt.org/download.html) to install the sbt launcher on your system. See [sbt documentation](http://www.scala-sbt.org/release/docs/Setup-Notes.html) for details about how to setup sbt. We recommend that you use the latest version of sbt. With sbt installed, you can use our [giter8](http://www.foundweekends.org/giter8/) templates for Java or Scala to [[create a new project with a single command\|NewApplication]].


		## Introduction to Play

		As illustrated below, Play is a full-stack framework with all of the components you need to build a Web Application or a REST service, including: an integrated HTTP server, form handling, Cross-Site Request Forgery (CSRF) protection, a powerful routing mechanism, I18n support, and more. Play integrates with many object relational mapping (ORM) layers. It supports [[Anorm]], [[Ebean\|JavaEbean]], [[Slick\|PlaySlick]], and [[JPA\|JavaJPA]] out-of-the-box, but many customers use NoSQL or REST layers and other ORMs.


		[[images/play-stack.png]]

		Play APIs are available in both Java and Scala. The Framework uses [Akka](https://akka.io) and [Akka HTTP](https://doc.akka.io/docs/akka-http/current/index.html) under the hood. This endows Play applications with a stateless, non-blocking, event-driven architecture that provides horizontal and vertical scalability and uses resources more efficiently. Play projects contain Scala components, but you do not need to learn Scala to use Play successfully if you are a Java developer.


		In the browser, enter the following URL and pass in any name as a query parameter to the hello method: <http://localhost:9000/hello?name=MyName>. Play responds with a helpful compilation error that lets you know that the render method in the return value requires a typed parameter:

		[[images/hello-error.png]]


		Play is a high-productivity Java and Scala web application framework that integrates components and APIs for modern web application development. Play was developed by web developers for web application development.

		You will find Play's Model-View-Controller (MVC) architecture familiar and easy to learn. Play provides concise and functional programming patterns. And, the large community developing Play applications provides an excellent resource for getting your questions answered.

		@@ -0,0 +1,114 @@
		<!--- Copyright (C) 2009-2018 Lightbend Inc. <https://www.lightbend.com> -->

		# Implementing Hello World

		@@ -0,0 +1,51 @@
		<!--- Copyright (C) 2009-2018 Lightbend Inc. <https://www.lightbend.com> -->

		# Play Application Overview

Uh oh!

Getting starter experience improvements #8385

Getting starter experience improvements #8385

Uh oh!

Conversation

marcospereira commented Apr 27, 2018

Purpose

References

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!