Doc changes to make doc consistent with website pages #8295

rstento · 2018-03-14T21:30:16Z

saving a delta
checking in a delta
Another set of small changes
All reorganized, edited, links changed to point to Tech Hub, most commands tested (except for all on the IDE page).
added a cross-ref
Upgrade twirl (Upgrade twirl #8258)

Pull Request Checklist

Have you read How to write the perfect pull request?
Have you read through the contributor guidelines?
Have you signed the Lightbend CLA?
Have you referenced any issues you're fixing using commit message keywords?
Have you added copyright headers to new files?
Have you checked that both Scala and Java APIs are updated?
Have you updated the documentation for both Scala and Java sections?
Have you added tests for any changed functionality?

Helpful things

Fixes

Fixes #xxxx

Purpose

What does this PR do?

Background Context

Why did you take this approach?

References

Are there any relevant issues / PRs / mailing lists discussions?

* saving a delta * checking in a delta * Another set of small changes * All reorganized, edited, links changed to point to Tech Hub, most commands tested (except for all on the IDE page). * added a cross-ref * Upgrade twirl (playframework#8258)

gmethvin · 2018-03-16T22:09:07Z

documentation/manual/gettingStarted/Anatomy.md

 # Anatomy of a Play application

-## The Play application layout
+When you create a Play application from a template or use one of the examples, the project will be structured in a standard way. See the following topics for more information:


I think this is a bit confusing. It suggests all these sections are about a specific layout. There are actually two different structures, the traditional Play layout and the default SBT layout (described by "project structure" and "default SBT layout" here). I think we need to better introduce the fact that there are multiple different layouts. WDYT @marcospereira @richdougherty?

Thanks @gmethvin for the clarification. A further question before I change this. Isn't the "default SBT layout" the one that the seed templates and examples use now? When would a developer use the "traditional" Play layout? Only with older versions, or ....?

The default sbt (or Maven) layout is different from the one most of the examples use. Play uses a custom layout by default (i.e. projects using the PlayScala and PlayJava sbt plugins use this layout). I guess I would call that the "Play web app layout". But it is possible to use the default sbt layout with Play as well, for example it is used here: https://github.com/gmethvin/play-scala-minimal-service-example. Lagom apps also use the default sbt layout. Eventually we might switch to recommending the default sbt layout as the "default" in Play but for now it's only the default in the PlayService plugin.

gmethvin · 2018-03-16T22:11:22Z

documentation/manual/gettingStarted/Anatomy.md

 ```

-## The `app/` directory
+The following provide more details on the contents of:


I think it would be fine to change these to lower-level headings and have a short intro like "The following sections provide more detail on different directories in the Play web app layout."

gmethvin · 2018-03-16T22:17:44Z

documentation/manual/gettingStarted/NewApplication.md

+1. Unzip the project in a convenient location.
+1. In a command window, navigate to the top level project directory.
+1. Enter one of the following commands:
+   On OSx or Linux systems: `/sbt run` or `./gradle runPlayBinary`


I would say macOS instead of OSX. Also I think it would be ./sbt run. Are we doing a ./gradle wrapper in the local directory too now?

If you google how to refer to macOS, the current preferred style is OSX. @gmethvin , thanks for catching the typo in ./sbt run. I believe @marcospereira gave me the gradle example, so I believe it is correct.

I'm pretty sure Apple changed the branding to macOS recently from OS X.

gmethvin · 2018-03-16T22:21:00Z

documentation/manual/gettingStarted/Tutorials.md

+Play's documentation shows the available features and how to use them, but does not show how to create an application from start to finish.  This is where [[tutorials and examples|NewApplication]] come in.

-Tutorials and examples are useful for showing a single application at work, especially when it comes to integrating with other systems such as databases or Javascript frameworks.
+<!-- Tutorials and examples are useful for showing a single application at work, especially when it comes to integrating with other systems such as databases or Javascript frameworks.


Why is this stuff being commented out?

@gmethvin, I wanted to leave it so you could compare how it was organized previously. I intend to remove it before asking for a merge. Since everything has been reorganized, it no longer makes sense here. And, WRT the specific sentence you highlighted, I didn't see that it added particular value. That's what most people expect from examples, right?

ok I was just wondering if there's a reason for commenting rather than removing

gmethvin · 2018-03-16T22:22:50Z

documentation/manual/gettingStarted/Tutorials.md

@@ -1,17 +1,17 @@
 <!--- Copyright (C) 2009-2017 Lightbend Inc. <https://www.lightbend.com> -->
-# Play Tutorials
+# Other resources


Is this meant to be just third-party (non-Play-maintained) examples? Maybe label it as "Third-party examples" or something like that? "Other examples" feels really general.

@gmethvin , they are not all third-party.

gmethvin · 2018-03-16T22:27:13Z

documentation/manual/gettingStarted/index.toc

-PlayConsole:Using the Play console
-IDE:Setting-up your preferred IDE
+Installing:Introduction
+NewApplication:Examples and templates


Its kind of weird that the name (NewApplication) of the page differs from the title. Is this really meant to be examples or should this be called something like "New application templates and examples"? It seems to be both about starting a new app and about templates.

NewApplication was the original name of the page, @gmethvin. I didn't change it to avoid losing google ranking. There is probably a way to handle this by providing a redirect, but I'm not sure how to do that?

gmethvin · 2018-03-16T22:28:16Z

documentation/manual/gettingStarted/Tutorials.md

+# Other resources

-Play's documentation shows the available features and how to use them, but the documentation will not show how to create an application from start to finish.  This is where tutorials and examples come in.
+Play's documentation shows the available features and how to use them, but does not show how to create an application from start to finish.  This is where [[tutorials and examples|NewApplication]] come in.


I would link to the specific subsection with the examples.

@gmethvin, I didn't do this because they really need to start at the top of the page. And, once they scan the first paragraph, the links are right there, and they should know the difference between examples and templates.

gmethvin

Overall there are a lot of great improvements here and I'm glad @rstento is taking a closer look at this.

I'm wondering if it actually makes sense to combine the Installing and NewApplication pages. I guess the page could get too long, but it'd be nice to have everything you need to get started on one page.

gmethvin · 2018-03-19T03:45:31Z

documentation/manual/gettingStarted/Anatomy.md

-## The `app/` directory
+The following provide more details on the contents of:
+
+* [The `app/` directory](#The-`app/`-directory)


Can we autogenerate the TOC for this subsection? If not I'd be wary of adding these sections since we'll have to remember to manually update it.

I agree @gmethvin, but I don't know how to implement this.

I think we should omit this for now and do something after the fact. I really like how the Akka docs do it, for example on https://doc.akka.io/docs/akka/2.5/stream/stream-flows-and-basics.html you can see the subsections in the sidebar.

gmethvin · 2018-03-19T03:47:00Z

documentation/manual/gettingStarted/Installing.md

+
+## Choosing a build tool
+
+Because Play Framework libraries are available from [Maven Repository](https://mvnrepository.com/artifact/com.typesafe.play), you can use any Java build tool to build a Play project. However,   [sbt](http://www.scala-sbt.org/) (simple build tool) provides the development experience Play is known and loved for, such as routes, template compilation, and auto-reloading.  For example,  `sbt run` builds and runs an HTTP server and your application so that you can immediately view your work. 


I think it would be nice to mention that there are also third-party plugins for maven and gradle that provide a similar experience, but they are not officially supported by the Play team (and may not always be up to date):

https://docs.gradle.org/current/userguide/play_plugin.html

https://github.com/play2-maven-plugin/play2-maven-plugin

gmethvin · 2018-03-19T03:54:59Z

documentation/manual/gettingStarted/Installing.md

+# Introduction

-This page shows how to download, install and run a Play application.  There's a built in tutorial that shows you around, so running this Play application will show you how Play itself works!
+In contrast with web frameworks that were designed to support large eco-systems, such as Java EE, Play was developed by web developers&mdash;for web development. Play saves precious development time by directly supporting common tasks and hot reloading so that you can immediately view the results of your work. As a full-stack framework, it includes all of the components you need to build a web application such as an integrated HTTP server, form validation, Cross-Site Request Forgery (CSRF) protection, RESTful web services API, and more.


I'm not sure what you mean by "support large eco-systems". To a newcomer this might suggest that there's a small amount of software out there that is part of the Play ecosystem. I suppose what you're saying is that the libraries Play provides are focused on web development?

@gmethvin, yes, exactly. I will reword to "large eco-systems that include much more than web development, ..."

I still sort of feel like it feels limiting to mention "large eco-systems". Can we just remove the "In contrast ..." part?

I guess I don't understand what this is meant to suggest. Play is part of a large ecosystem of Java and Scala tools. It's not like you can't use Play with other tools that do other things, it's just that Play itself is focused on developing web applications and web services.

gmethvin · 2018-03-19T03:57:15Z

documentation/manual/gettingStarted/Installing.md

+Play offers both Java and Scala APIs. Java developers find Play's Model-View-Controller (MVC) architecture familiar and easy to learn. Scala developers appreciate using the concise and familiar functional programming patterns. The large community developing Play applications provides an excellent resource for getting questions answered.

-Play requires Java 1.8.  To check that you have the latest JDK, please run:
+Play is non-opinionated about database access, and integrates with many object relational mapping (ORM) layers.  It supports Anorm, Ebean, Slick, and JPA, out-of-the-box but many customers use NoSQL or REST layers and other ORMs. 


I would link to the relevant documentation pages in "It supports Anorm, Ebean, Slick and JPA out of the box"

@gmethvin, do you mean the relevant examples, because I don't see any specific documentation on most of these?

We have documentation pages for all four:

https://www.playframework.com/documentation/2.6.x/JavaEbean
https://www.playframework.com/documentation/2.6.x/ScalaAnorm
https://www.playframework.com/documentation/2.6.x/PlaySlick
https://www.playframework.com/documentation/2.6.x/JavaJPA

marcospereira · 2018-04-03T16:35:06Z

I'm closing this since @rstento, and I are working on multiple fronts (website, docs, sample projects, etc.) to improve Play's getting started experience.

@gmethvin as always, thank you for reviewing. We are for sure considering your insights and comments here. ;-)

gmethvin reviewed Mar 16, 2018

View reviewed changes

gmethvin changed the title ~~Doc changes to make doc consistent with website pages (#1)~~ Doc changes to make doc consistent with website pages Mar 19, 2018

gmethvin reviewed Mar 19, 2018

View reviewed changes

marcospereira closed this Apr 3, 2018

marcospereira mentioned this pull request Apr 27, 2018

Getting starter experience improvements #8385

Merged


		## Choosing a build tool

		Because Play Framework libraries are available from [Maven Repository](https://mvnrepository.com/artifact/com.typesafe.play), you can use any Java build tool to build a Play project. However, [sbt](http://www.scala-sbt.org/) (simple build tool) provides the development experience Play is known and loved for, such as routes, template compilation, and auto-reloading. For example, `sbt run` builds and runs an HTTP server and your application so that you can immediately view your work.

Uh oh!

Doc changes to make doc consistent with website pages #8295

Doc changes to make doc consistent with website pages #8295

Uh oh!

Conversation

rstento commented Mar 14, 2018

Pull Request Checklist

Helpful things

Fixes

Purpose

Background Context

References

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gmethvin Mar 20, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

gmethvin left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

marcospereira commented Apr 3, 2018

Uh oh!

Reviewers

Assignees

Labels

gmethvin Mar 20, 2018 •

edited

Loading

gmethvin left a comment •

edited

Loading