New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First set of changes to remove "download" terminology #192

Merged
merged 9 commits into from Apr 3, 2018

Conversation

Projects
None yet
4 participants
@rstento
Copy link
Contributor

rstento commented Feb 14, 2018

And to simplify instructions for getting started. @marcospereira, as we discussed, the next step would be to move the list of older versions from the "Try Play" page. But, in the meantime, I'll be submitting a few minor doc changes to make the docs consistent with the website.

@richdougherty @jroper @marcospereira please review.

@marcospereira

This comment has been minimized.

Copy link
Member

marcospereira commented Feb 15, 2018

Hi Ruth,

I would prefer a smaller and super concise experience for this page. For example:

First time using Play

Use one of starter projects. They include the sbt build tool and Gradle so you don't need to install anything.

  1. Play Java Starter Example Download (zip) View on GitHub
  2. Play Scala Starter Example Download (zip) View on GitHub

After donwloading, enter the following at the prompt to run the starter project:

./sbt run

Or if you are using Gradle, run:

./gradlew runPlayBinary

And then navigate to http://localhost:9000.

I already have sbt installed

If you already know a bit about Play and have sbt 0.13.13 or higher installed, you can create your own Play project using the sbt new:

sbt new playframework/play-scala-seed.g8

Or for Java based project:

sbt new playframework/play-java-seed.g8

Then change into the top level directory and run it using:

sbt run

Or if you are using Gradle:

./gradlew runPlayBinary

And then navigate to http://localhost:9000.

Want to see what Play can do? Download an example project!

See Lightbend Tech Hub for a organized list of example projects that each showcase a feature or a use case so that you can see Play at work.
Button to Lightbend Tech Hub

Of course, this is just to express the idea. But, comparing to "Try Akka" and "Try Lagom" this is already a lot of stuff.

What do you think?

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Feb 15, 2018

@marcospereira

This comment has been minimized.

Copy link
Member

marcospereira commented Feb 20, 2018

What would you all think of making the try play page even shorter, just mentioning pre-requisites, recommending that newbies start with the starter project, and pointing to Tech Hub?

@rstento as a developer, I like the idea of having a small set of commands a need to run to get started. That is why I was proposing to have a stripped down page, but with some commands, people can run. That is why I suggested having the minimum amount of text/instructions to go from zero to see a Play application running. Everything else (list os sample, old releases) can be moved to other pages (I like the idea of using Tech Hub here).

So, building on top of what you have right now, what do you think about this (missing links):

It's quick and easy to get started

If you already have sbt installed, just run the command below:

For Scala

sbt new playframework/play-scala-seed.g8
cd your-application-directory
sbt run

For Java

sbt new playframework/play-java-seed.g8
cd your-application-directory
sbt run

You can also use Gradle instead of sbt run if you want:

./gradlew runPlayBinary

And then go to http://localhost:9000.

See our sample projects

Lightbend Tech Hub has a variety of Play example projects that you can download. Just unzip, build, and run the projects using sbt or Gradle. The build tool automatically downloads everything you need to start working with Play.

For your first experience with Play, we suggest the Starter Example for Java or Scala. The other examples available from Tech Hub showcase a particular feature or illustrate how to satisfy a common use case. When you are ready to build your own app, use a seed template that sets up the appropriate project structure and dev environment for you.

HUGE BUTTON LINKING TO TECH HUB

What do you think?

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Feb 20, 2018

@marcospereira

This comment has been minimized.

Copy link
Member

marcospereira commented Feb 20, 2018

@marcospereira, For first timers, I don’t believe running the commands to
end up with an empty seed project is the way to go. That’s why I worked on
that tutorial that explains what they have once they create a project and
what to do next. The usability problem with many of Lightbend examples is
that they come with no explanation (or not enough) Developers such as
yourself, who are highly motivated will dig in and figure things out. But
those who are just curious and and are encountering it for the first time
are likely to just quit if they don’t see a clear path. I saw this over and
over when doing usability tests with Lagom.

Totally agree with you here. As you said before, it is probably because we are discussing a single page without considering the tutorial and other sections of the docs. But yeah, people need a "whats next" after creating an application.

My plan is that we recommend as a first experience the existing getting
started example, when they unzip it, they will have the readme that
explains how to run it and when they run, the first page that displays will
explain the example and contain the steps. So this revised example will
include the hello world steps I developed for the tutorial. This is what I
plan to work on after making the documentation consistent with the new Try
Play page.

That sounds good. I wonder how to keep this well integrated into the docs (I mean, how to have the tutorial as part of the docs too, so people can find it using Google, etc.).

I think once you see it all put together, you will see that it simplifies
the experience. Then we can test it, and tweak as necessary.

Let's go for it. I agree that it will be simpler to iterate over something that exists. ;-)

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Feb 22, 2018

@marcospereira, I am happy with this version for now. It does provide the commands to build and run (which aren't readily available for gradle anywhere I could find), but is still short and points to both Tech Hub for examples, and doc for the command to use seed templates. It also removes the now unused logic from the view and the controller. Here is the screen shot, if you are happy with it, please merge:
image

Note, that I adopted the left-aligned text of the other pages, but so far have been unsuccessful in getting this page to have the common sidebar. If you can fix, great, otherwise I'll look at it when I have time. It actually looks less cluttered without it (IMHO).

@marcospereira

This comment has been minimized.

Copy link
Member

marcospereira commented Feb 22, 2018

Thank you so much, @rstento.

There are some things I think we can rename/move around (use /getting-started instead /download for the URL), but I can take care of it.

Note, that I adopted the left-aligned text of the other pages, but so far have been unsuccessful in getting this page to have the common sidebar. If you can fix, great, otherwise I'll look at it when I have time. It actually looks less cluttered without it (IMHO).

Ok. I can help you with that. Let me take a closer look. Again, thank you!

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Feb 22, 2018

@marcospereira

This comment has been minimized.

Copy link
Member

marcospereira commented Feb 22, 2018

@rstento I've made some additional commits here to fix the problems you described and also rename some files/routes (with a proper redirect from /download to /getting-started) to be consistent with the page they represent. Here is how the getting started page is looking after my changes:

screen shot 2018-02-22 at 3 43 18 pm

And here is how the releases page is looking:

screen shot 2018-02-22 at 3 43 57 pm

I've decided to keep the sidebar so that all pages are consistent with each other.

Please validate so that we can merge this and publish the new version.

Best.

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Feb 22, 2018

Looks great! Thanks for fixing the formatting and handling the routing.

@wsargent

This comment has been minimized.

Copy link
Member

wsargent commented Mar 19, 2018

FYI, you may be interested in Kelley Robinson's experience here: https://twitter.com/kelleyrobinson/status/975376067669184513

  1. Ran into Play 1 documentation based off google search, warning above search bar didn't help: https://twitter.com/kelleyrobinson/status/975376400025903104

  2. Was thrown off by the "download" phrase on the starter project but DID see it ("I don't really want to install Play (there is a link above that)"), decided to use the seed instead (maybe stronger warning on seed section?): https://twitter.com/kelleyrobinson/status/975378113839366145

  3. Got the seed but it took 20 minutes because she didn't use the .zip file (we need to explain that downloading zip file is much faster): https://twitter.com/kelleyrobinson/status/975381514862125056

  4. Didn't find any leads from the seed project, so downloaded an example from the downloads page instead, jumping straight past the starter projects again: https://twitter.com/kelleyrobinson/status/975384188533829633

  5. Also the "route" search from algolia is flat, so it treats javascript routing the same as routing in general (not sure what we can do about this -- recommend "site:playframework.com" and use google custom searches instead of algolia? But then it is not version specific) https://twitter.com/kelleyrobinson/status/975384188533829633

  6. Then went to look for documentation in Github but ended up on the documentation subproject README which does not have contributing because subproject. Added playframework/playframework#8300 for links back to base: https://twitter.com/kelleyrobinson/status/975386818278543360

  7. Calls out "missing tutorial" which is essentially the starter project's welcome.html page https://github.com/shekhargulati/play-the-missing-tutorial/blob/master/01-hello-world.md

@gmethvin
Copy link
Member

gmethvin left a comment

I think it would be a better experience if we keep the starter project downloads available directly on the Play website. Since we already have integration with the example code service it should not be a huge burden to maintain.

The thing I don’t like about the Tech Hub page is that it doesn’t consistently provide pre requisites or links to guides. The thing I do like is that it gives you room for a few sentences to describe the point of the example project.

We can get the best of both worlds IMO by having a list of example projects on the "Try Play" page and allowing you to expand each item to see a long description. I think that information is already available through the example code service API so it should not be hard for us to implement. That way the user never has to leave the Play website and it feels like a fully integrated experience.

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Mar 19, 2018

@wsargent

This comment has been minimized.

Copy link
Member

wsargent commented Mar 19, 2018

Another note from the tweets: needs to be clear you have both zip and github versions of the starter projects, so people can see the starter without downloading the starter or running sbt

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Mar 19, 2018

@wsargent

This comment has been minimized.

Copy link
Member

wsargent commented Mar 19, 2018

I would argue that had Kelley found simpler and more consistent doc, it would have avoided the majority of her problems.

Yeah, I'm wondering if the https://www.playframework.com/documentation/2.6.x/NewApplication page is a net positive, given that it seems to duplicate "Try Play."

Same with https://www.playframework.com/documentation/2.6.x/Tutorials#Play-Maintained-Seeds-and-Example-Templates -- this is a duplication of existing info and potentially a source of more confusion.

@rstento

This comment has been minimized.

Copy link
Contributor Author

rstento commented Mar 19, 2018

rstento and others added some commits Feb 14, 2018

@marcospereira marcospereira force-pushed the rstento:change-tab-name branch from 922fe8e to 8074497 Apr 3, 2018

@marcospereira

This comment has been minimized.

Copy link
Member

marcospereira commented Apr 3, 2018

I'm merging this as is since there are other code changes (in CSS and JavaScript). But I will open a follow-up request with the content that @rstento and I are working on.

@wsargent thanks for digesting Kelly Robinson's tweets. Those are super valid points, and we are considering them.

@marcospereira marcospereira merged commit 2688fcb into playframework:master Apr 3, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

marcospereira added a commit to marcospereira/playframework.com that referenced this pull request Apr 9, 2018

Improvements for the "try-play" page
This is a follow up of playframework#192 by @rstento. There are some changes
here that depends on documentation improvements too, so another
pull request will be made to improve Play docs and make it consistent
with the changes here.

marcospereira added a commit to marcospereira/playframework.com that referenced this pull request Jun 26, 2018

Improvements for the "try-play" page
This is a follow up of playframework#192 by @rstento. There are some changes
here that depends on documentation improvements too, so another
pull request will be made to improve Play docs and make it consistent
with the changes here.

renatocaval added a commit to renatocaval/playframework.com that referenced this pull request Sep 14, 2018

marcospereira added a commit that referenced this pull request Sep 21, 2018

Improvements for the "try-play" page (#206)
* Improvements for the "try-play" page

This is a follow up of #192 by @rstento. There are some changes
here that depends on documentation improvements too, so another
pull request will be made to improve Play docs and make it consistent
with the changes here.

* Minor fixes after review

* Configure redirect from Installing to Requirements
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment