Merge pull request #25 from raspberrypilearning/draft

Draft

Author: MarcScott

en/step_1.md

@@ -6,7 +6,7 @@ You'll set up a web server and create a simple website using Flask, Python, and
 
 ![flask web app](images/showcase.png)
 
-The web server will be able to react to the user inputting dynamic content, turning your website into a web application capable of doing more than just showing static information.
+The web server will be able to react to the dynamic content that the user inputs, so your website will be a web application that can more than just show static information.
 
 --- collapse ---
 
@@ -16,7 +16,7 @@ title: What you will need
 
 ### Hardware
 
-+ Computer capable of running Python 3
++ A computer capable of running Python 3
 
 ### Software
 
@@ -30,7 +30,7 @@ title: What you will need
 title: What you will learn
 ---
 
-- How to install Python modules using pip
+- How to install Python modules using `pip`
 - How to build a basic web app with Python and Flask
 
 This resource covers elements from the following strands of the [Raspberry Pi Digital Making Curriculum](https://www.raspberrypi.org/curriculum/):

en/step_2.md

@@ -1,8 +1,8 @@
 ## Build a Flask website
 
-You're going to set up a basic web application with Flask and Python.
+First, set up a basic web application with Flask and Python.
 
-If you don't already have Python 3 on your computer you will need to download and install it.
+If you don't have Python 3 on your computer, you need to download and install it.
 
 --- task ---
 
@@ -12,7 +12,7 @@ If you don't already have Python 3 on your computer you will need to download an
 
 --- /task ---
 
-You will also need to install the Flask package. 
+You also need to install the Flask package. 
 
 --- task ---
 
@@ -26,7 +26,7 @@ Once Flask is installed, you can create your web application.
 
 --- task ---
 
-Open a terminal or command prompt window, and make a new directory called `webapp` for your project.
+Open a terminal or command prompt window, and use the `mkdir` command to create a new directory called `webapp`.
 
 ```bash
 mkdir webapp
@@ -36,7 +36,7 @@ mkdir webapp
 
 --- task ---
 
-Use the change directory command `cd` to open the new directory.
+Use the 'change directory' command `cd` to open the new directory.
 
 ```bash
 cd webapp
@@ -45,19 +45,19 @@ cd webapp
 
 --- task ---
 
-Open Python 3 IDLE.
+Open Python 3 IDLE, and create a new file by clicking on**File** and then on **New file**.
 
 --- /task ---
 
 --- task ---
 
-Create a new file by clicking **File** and then **New file**, and save it as `app.py` inside the `webapp` folder you just created.
+Save the new file with the name `app.py` inside the `webapp` folder.
 
 --- /task ---
 
 --- task ---
 
-Now enter the following lines of code into the blank `app.py` window:
+Now enter the following lines of code into the `app.py` file:
 
 ```python
 from flask import Flask
@@ -72,19 +72,19 @@ if __name__ == '__main__':
     app.run(debug=True, host='0.0.0.0')
 ```
 
-You will explore this code in more detail in the next step, but for now let's keep it simple and make sure everything works.
-
 ![idle](images/idle-flask.png)
 
+You will explore this code in more detail in the next step. But first, make sure the code works.
+
 --- /task ---
 
 --- task ---
 
-Save your changes by clicking **File** and then **Save**, or by pressing <kbd>Ctrl</kbd> and <kbd>S</kbd>. 
+Save your changes by clicking on **File** and then on **Save**, or by pressing <kbd>Ctrl</kbd> and <kbd>S</kbd> at the same time. 
 
 --- /task ---
 
-You will need to run your web app from the terminal/command prompt window you opened earlier.
+You need to run your web app from the terminal/command prompt window you opened earlier.
 
 --- task ---
 
@@ -98,7 +98,7 @@ Enter the command `python app.py` into the command prompt window.
 
 --- /task ---
 
-If everything has been set up correctly, you should see an output similar to this:
+If your code is correct, the window should show you output similar to this:
 
 ```
  * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
@@ -111,9 +111,9 @@ If everything has been set up correctly, you should see an output similar to thi
 
 --- task ---
 
-Open your web browser and enter the URL `http://127.0.0.1:5000/`. You should see a white screen with the words `Hello world`.
+Now open your web browser and enter the URL `http://127.0.0.1:5000/`. You should see a white screen with the words `Hello world`.
 
-**Note:** `127.0.0.1` means 'home', i.e. this computer. `:5000` means 'port 5000', which is the port the web server is running on.
+**Note:** `127.0.0.1` means 'home', i.e. your computer. `:5000` means 'port 5000', which is the port the web server is running on.
 
 --- /task ---
 

en/step_3.md

@@ -2,9 +2,9 @@
 
 Now you're going to add a new page to your web app by creating a new **route**.
 
-In a web application, a route is a certain path into your website, determined by the URL the user types into their web browser's address bar. It's up to you which routes are enabled and what each of them does.
+In a web application, a route is a certain path into your website, determined by the URL the user types into their web browser's address bar. You create the routes and determine what each route does.
 
-In the 'Hello world' example, we used a single route:
+In the code you already have in `app.py`, there is a single route:
 
 ```python
 @app.route('/')
@@ -15,23 +15,23 @@ def index():
 This route is made up of three parts:
 
 - `@app.route('/')`: this determines the entry point; the `/` means the root of the website, so `http://127.0.0.1:5000/`
-- `def index()`: this is the name you give to the route; this one is called `index`, because it's the index (or home page) of the website
+- `def index()`: this is the name you give the route, in this case `index`, because it's the index (or homepage) of the website
 - `return 'Hello world'`: this is the content of the web page, which is returned when the user goes to this URL
 
-The 2nd part of the `app.py` code runs the web server and your app:
+The second half of the `app.py` code runs the web server and your app:
 
 ```python
 if __name__ == '__main__':
     app.run(debug=True, host='0.0.0.0')
 ```
 
-**Note:** the `host='0.0.0.0'` means the web app will be accessible to any device on the network.
+**Note:** the `host='0.0.0.0'` means the web app is accessible to any device on the network.
 
-The following instructions will show how to create a new page and route called 'cakes', but feel free to change this name and content to be whatever you want.
+The following instructions show how to create a new page and route called 'cakes'. If you want, you can change the name and and the content to be whatever you wish.
 
 --- task ---
 
-Create a new route by adding these lines of code below the first route:
+To create a new page and a route to it, add these lines of code below where the first page and route are created in `app.py`:
 
 ```python
 @app.route('/cakes')
@@ -70,7 +70,7 @@ if __name__ == '__main__':
 
 --- task ---
 
-Save your code and navigate to your 'cakes' page in the browser at `127.0.0.1:5000/cakes`. You should see a web page with the text "Yummy cakes!" on it:
+Save your code and navigate to the 'cakes' page in the browser at the address `127.0.0.1:5000/cakes`. You should see a web page with the text "Yummy cakes!" on it.
 
 ![Yummy Cakes](images/flask-cakes.png)
 

en/step_4.md

@@ -1,12 +1,12 @@
-## Using HTML
+## Return HTML web pages
 
 Next, you'll modify your existing routes to return a full HTML web page rather than just simple text.
 
-The HTML web page will be created from a **template** that holds the static content of the page. You'll later learn how to insert data to create a dynamic version of the page.
+The HTML web page will be created from a **template** that holds the static content of the page. In a later section of this project, you'll learn how to insert data to create a dynamic version of the page.
 
 --- task ---
 
-First, create a `templates` directory in your `webapp` directory by entering this into the terminal or command prompt window:
+First, create a `templates` directory in your `webapp` directory by entering the following command into the terminal or command prompt window:
 
 ```bash
 mkdir templates
@@ -54,15 +54,15 @@ from flask import Flask, render_template
 
 --- task ---
 
-Finally, you'll need to modify your `index()` function to return the `index.html` HTML template instead of the normal text. Change the code inside the definition so that the code looks like this:
+Finally, modify your `index()` function to return the `index.html` HTML template instead of the normal text. Change the code inside the definition so that the code looks like this:
 
 ```python
 @app.route('/')
 def index():
     return render_template('index.html')
 ```
 
-Flask will look for `index.html` in the `templates` directory that the `app.py` program is in.
+This code makes Flask look for `index.html` in the `templates` directory that the `app.py` program is in.
 
 --- /task ---
 
@@ -78,7 +78,7 @@ Load the `http://127.0.0.1:5000/` page in your web browser to see your new HTML
 
 ![my website](images/flask-template.png)
 
-In this case it's not much different, as all you've done is added a HTML header, but there's plenty of scope to expand!
+In this case what you see is not much different, because the only new thing is a HTML header. There's plenty of scope to add other things!
 
 --- /task ---
 

en/step_5.md

@@ -1,12 +1,12 @@
-## Challenge: Add a HTML template to the second page
+## Challenge: add a HTML template to the second page
 
-Now you've learnt how to change your 'index' page to use a HTML template, do the same for your 'cakes' page!
+Now you know how to change your 'index' page to use a HTML template, make your 'cakes' page use a HTML template too!
 
 --- hints ---
 
 --- hint ---
 
-Repeat the same steps you've just followed to create a template for the cakes page.
+Repeat the steps in the previous project section to create and use a HTML template for the 'cakes' page.
 
 --- /hint ---
 

en/step_6.md

@@ -4,7 +4,7 @@ Now you'll add some Cascading Style Sheets (CSS) to add colour to your web page.
 
 --- task ---
 
-First, return to the terminal/command prompt window and navigate to the `webapp` directory. If you're in the `templates` directory, go back up one level with `cd ..`.
+First, return to the terminal/command prompt window and navigate to the `webapp` directory. If you're in the `templates` directory, go up one level with the command `cd ..`.
 
 --- /task ---
 
@@ -20,7 +20,7 @@ mkdir static
 
 --- task ---
 
-Create a new file in IDLE by clicking **File** and **New File**, and save this file as `style.css` in the `static` folder you just created.
+Create a new file in IDLE by clicking **File** and **New File**, and save this file as `style.css` in the `static` folder.
 
 --- /task ---
 
@@ -37,7 +37,7 @@ body {
 
 ![idle css](images/idle-css.png)
 
-**Note:** you have used colour names here, but you could also create colours using hex codes like `#ff0000` (red).
+**Note:** this code contains colour names, but you could also create colours using hex codes like `#ff0000` (red).
 
 --- /task ---
 
@@ -66,15 +66,15 @@ Now modify your `index.html` HTML template to include the CSS rules by adding a
 
 --- task ---
 
-Save the change to `index.html` and refresh your browser. You should see a colourful version of the web app!
+Save the change to `index.html` and refresh your browser. You should see a colourful version of your web app!
 
 ![Flask app with colour](images/flask-app-with-colour.png)
 
 --- /task ---
 
-If your web app doesn't look right, you may not have saved your CSS file in the right place.
+If your web app doesn't look right, your CSS file might not be in the right directory.
 
-By now you've created a number of files and directories for your web app. It is worth quickly double-checking your `webapp` project directory, which should contain the following and have a structure like this now:
+You now have a number of files and directories for your web app. It is worth making sure your `webapp` project directory contains the following files and has the following structure:
 
 ```
 ├── app.py

en/step_7.md

@@ -1,22 +1,24 @@
-## Adding dynamic content
+## Add dynamic content
 
-So far you've learned to deliver static HTML web pages using templates. Lets add some dynamic content to the pages to display different information. Large websites like Facebook, YouTube and BBC News show different content depending on the page you visit, even though the templates are very similar.
+Now you know how to deliver static HTML web pages using templates. Large websites like Facebook, YouTube and BBC News have dynamic content: these websites show different content depending on the page you visit, even though the templates are very similar.
 
-Now you'll create a new route on your website so that when you go to `http://127.0.0.1/hello/name`, it will say "Hello name!" and replace 'name' with whatever you put there; so `/hello/Paul/` will display "Hello Paul!".
+You will now add some dynamic content to your pages so they can display different information. 
+
+Now you will create a new route on your website so that when you go to `http://127.0.0.1/hello/name`, the page says 'Hello name!', replacing 'name' with whatever you put there. So for example, `/hello/Dana/` displays 'Hello Dana!'.
 
 --- task ---
 
-Create a new route in your application like so:
+Add the following code to create a new route in your application:
 
 ```python
 @app.route('/hello/<name>')
 def hello(name):
     return render_template('page.html', name=name)
 ```
 
-- `@app.route('/hello/<name>')` - the `<name>` part means it passes the name into the `hello` function as a variable called `name`
-- `def hello(name)` - this is the function that determines what content is shown - this time it takes the given name as a parameter
-- `return render_template('page.html', name=name)` - here we look up the template `page.html` and pass in the variable `name` from the URL, so the template can use it
+- `@app.route('/hello/<name>')`: the `<name>` part means it passes the name into the `hello` function as a variable called `name`.
+- `def hello(name)`: this is the function that determines what content is shown. Here, the function takes the given name as a parameter.
+- `return render_template('page.html', name=name)`: this code looks up the template `page.html` and passes in the variable `name` from the URL so that the template can use it.
 
 --- /task ---
 
@@ -36,11 +38,11 @@ Create a new HTML template called `page.html`, and add the following HTML code t
 
 --- task ---
 
-Save the files and visit `http://127.0.0.1:5000/hello/paul`. It should look like this:
+Save the files and visit `http://127.0.0.1:5000/hello/paul`. The page you see should look like this:
 
 ![Hello Paul!](images/flask-hello-paul.png)
 
-Try it with different names!
+Try `http://127.0.0.1/hello/name` with different names!
 
 --- /task ---
 
@@ -50,23 +52,23 @@ Try it with different names!
 title: What's happening here?
 ---
 
-Flask uses `jinja`, a Python library for rendering templates. Using the braces (curly brackets) on this line:
+Flask uses `jinja`, a Python library for rendering templates. Look at this code with the braces (curly brackets):
 
 ```html
 <h1>Hello {{ name }}!</h1>
 ```
 
-... tells the template to render the variable `name` which was passed in the route function `hello`.
+This code tells the template to render the variable `name` that was passed in the route function `hello`.
 
-Visiting `127.0.0.1:5000/hello/` without a name will create an error. Think about how you can prevent this from happening.
+Visiting `127.0.0.1:5000/hello/` without a name creates an error. Try to think of a way to prevent this error.
 
 --- /collapse ---
 
 --- task ---
 
-Create a link to your new dynamic hello page from your index.
+Create a link to your new, dynamic hello page from your index.
 
-Edit `index.html` to add a link to your new hello page under the heading.
+Edit `index.html` to add a link to the hello page under the heading.
 
 ```html
 <h1>My website</h1>
@@ -77,7 +79,7 @@ Edit `index.html` to add a link to your new hello page under the heading.
 
 --- task ---
 
-Save your changes and refresh the index page to see the result.
+Save the changes to `index.html`, and then refresh the index page in the browser to see the updated version.
 
 ![flask app link](images/flask-app-link.png)
 

en/step_8.md

@@ -2,7 +2,7 @@
 
 - Add more CSS rules to each of your pages
 - Create links to your favourite web pages
-- Learn more about HTML, CSS and web development with [Coder Dojo](https://projects.raspberrypi.org/en/CoderDojo/21), [Mozilla Developer Network](https://developer.mozilla.org/en-US/Learn) and [Codecademy](https://www.codecademy.com/en/tracks/web)
-- Learn more about Flask using the [Flask documentation](http://flask.pocoo.org/docs)
-- Create a physical computing project with Raspberry Pi and use Flask to create a web interface to it, see [Matt Richardson's guide](http://mattrichardson.com/Raspberry-Pi-Flask/index.html) or [Ben Nuttall's BETT Bot](https://github.com/bennuttall/bett-bot)
+- Learn more about HTML, CSS, and web development with [CoderDojo](https://projects.raspberrypi.org/en/CoderDojo/21), [Mozilla Developer Network](https://developer.mozilla.org/en-US/Learn) and [Codecademy](https://www.codecademy.com/en/tracks/web)
+- Learn more about Flask from the [Flask documentation](http://flask.pocoo.org/docs)
+- Create a physical computing project with Raspberry Pi and use Flask to create a web interface to it — you could use [Matt Richardson's guide](http://mattrichardson.com/Raspberry-Pi-Flask/index.html) or [Ben Nuttall's BETT Bot code](https://github.com/bennuttall/bett-bot) for help