Expand this tutorial based on confused areas last night.

creature · creature · commit 771da299a554 · 2014-08-21T10:59:38.000+01:00
There were a couple of typos in this tutorial, as well as some parts
which tripped up the students I worked with last night. I've cleaned
those typos up, added some explanations for confusing bits, removed some
technical language in favour of plain English, and simplified some other
sections.
diff --git a/html/lesson1/tutorial.md b/html/lesson1/tutorial.md
@@ -33,9 +33,9 @@ We will be building this [example page](http://codebar.github.io/tutorials/html/
 
 ### HTML element anatomy
 
-An **element** is an HTML component _eg. paragraph, heading, table, list etc_
+An **element** is an HTML building block. There are paragraphs, headings, tables, links, lists, and many more.
 
-**Tags**, mark the opening and closing of an element.  They contain elements that show their purpose
+**Tags** mark the opening and closing of an element. They often contain other elements and text.
 
 `<tagname>some content</tagname>`
 
@@ -44,13 +44,21 @@ An **element** is an HTML component _eg. paragraph, heading, table, list etc_
 <h1>I am a heading</h1>
 ```
 
-Some elements are standalone, as they cannot contain anything else <tagname/>
+Some elements are standalone, as they cannot contain anything else. They look like this: `<tagname/>`
 
 ```html
 <br/>
 <img/>
 ```
 
+### Comments
+
+We can use a special kind of tag to add notes to our page. The computer will ignore them, but programmers can read them and understand how your code works.
+
+```html
+<!-- Note to self: this is where the header goes -->
+```
+
 ### DOCTYPE and HTML tags
 
 The doctype is the first thing that must be defined in an HTML page.
@@ -81,7 +89,7 @@ The **body** contains what is visible to the user.
 
 ## Let's get started!
 
-Let's start by defining the basic structure of our website.
+Let's start by defining the basic structure of our website. Create a new folder for your work called "HTML tutorial 1". Then create a new file called "index.html" in that folder. Here's what you should put in it:
 
 ```html
 <!DOCTYPE html>
@@ -90,11 +98,16 @@ Let's start by defining the basic structure of our website.
     <title>I love owls</title>
   </head>
   <body>
-    <!-- content -->
+    <!-- Put your page content in this body tag! -->
   </body>
 </html>
 ```
 
+> If you load this in your browser, do you see anything on the page?
+
+> What about in the browser's title bar or tab bar?
+
+
 ### Element: Heading
 
 Headings come in many sizes
@@ -106,7 +119,7 @@ Headings come in many sizes
 ##### `<h5>Heading</h5>`
 ###### `<h6>Heading</h6>`
 
-Add a heading to your page
+Add a heading to your page. Place it inside the page body.
 
 ```html
 <h1>Owls!</h1>
@@ -126,7 +139,7 @@ Elements can be nested inside each other. For example, by putting the `<h1>` ins
 
 Putting content into a `<p>` will make it look like a paragraph structure. This helps make the content of a page easier to read.
 
-Add the following to your page, after the title
+Add the following to your page body, after the `<h1>` heading:
 
 ```html
 <p>
@@ -179,10 +192,11 @@ Let's add a link to the bottom of our paragraph
 
 ### Element: Div `<div>`
 
-Div stands for _division_. It creates sections in an HTML document.
-We can use a div to contain out paragraph.
+Div stands for _division_. It creates sections in an HTML document. They don't affect the layout of your page - but they do help you group related elements together.
 
-Wrap your paragraph in a div and add a heading to it
+We can use a div to contain our paragraph.
+
+Wrap your existing paragraph in a div and add a new heading to it:
 
 ```html
 <div>
@@ -198,6 +212,7 @@ Wrap your paragraph in a div and add a heading to it
 </div>
 ```
 
+
 ### Element: List `<li>`
 
 There are two types of lists, **ordered** and **unordered**.
@@ -214,9 +229,11 @@ Let's list the reasons we like owls so much under the main heading of the page (
 </ol>
 ```
 
+> If you wanted to make this an unordered list, what would you change? How could you check it worked? Try it, then change your list back to an ordered list.
+
 ### Element: Image `<img>`
 
-So far we've learned a lot about how to add text to our page. But how about some media?
+So far we've learned a lot about how to add text to our page. But how about something to look at?
 
 Let's add some images!
 
@@ -234,7 +251,7 @@ Images are primarily made up of three attributes
 
 * the `<img>` tag
 * the `src` attribute, which lets the page know what image we want to view
-* the `alt` attribute, where we describe our image
+* the `alt` attribute, where we describe our image for people who can't see it
 
 Before the main heading of the page, add the following
 
@@ -244,10 +261,14 @@ Before the main heading of the page, add the following
 </div>
 ```
 
+> Remember: the `<head>` section is not the same as a heading! Make sure your new `<div>` is in the page body.
+
 > Can you see the codebar logo? What happens when you change logo to logo1?
 
-Let's add some more, this time, contained in a list.
-Do this underneath  `<h2>Why do I like owls so much?</h2>`
+> If you can't see your image, make sure you put it in the `images` folder.
+
+Let's add some more images. This time, we'll put them in a list.
+Do this underneath  the `<h2>Why do I like owls so much?</h2>` heading.
 
 ```html
 <ul>
@@ -261,11 +282,11 @@ So a list can not only contain text, but other elements as well.
 
 ### Adding a link on multiple elements
 
-Links can contain not just text, but images or even a number of elements within.
+Links can contain many elements - not just text.
 
-Let's link some pictures and text to a video. It can be handy when we want the user to get to where we want them without needing to click on text.
+Let's use some pictures and text to link to a video. It can be handy when we want the user to get to where we want them without needing to click on text.
 
-Add that underneath the ordered list we defined earlier.
+Add this underneath the ordered list about why we like owls.
 
 ```html
 <div>
@@ -279,31 +300,35 @@ Add that underneath the ordered list we defined earlier.
 ```
 
 > Click any of the images. Can you get to the link's page?
+> What happens if you take the `<br/>` tag out? Remember to put it back afterwards!
+
+### Special characters and more formatting
+
+Some characters have special meaning in HTML. For instance, we use < and > to make HTML tags, and we use " to wrap our attributes. But what if we wanted to use those characters in our page?
 
-### ASCII and more formatting
+One way is to use **HTML entities**. These have an ampersand, a name, then a semicolon. Here's the HTML entity for a quote character: `&quot`.
 
-**ASCII** code is a way to represent text in ways that all computers can understand.
-[Here](http://htmlandcssbook.com/extras/html-escape-codes/) is a list with codes, their representation and HTML number.
+You can also use a numerical format to produce special characters. [Here's a list](http://htmlandcssbook.com/extras/html-escape-codes/) of some common entities.
 
-Add a small rhyme to your page, wrapped with quotes using ASCII code.
+Add a small rhyme to your page, wrapped with quotes using HTML entities.
 
 ```html
 <div>
   <p>
     <strong>
       <em>
-       &#34;A wise old owl sat on an oak;  The more he saw the less he spoke; <br>
-       The less he spoke the more he heard; Why aren&#39;t we like that wise old bird?&#34;
+       &quot;A wise old owl sat on an oak;  The more he saw the less he spoke; <br>
+       The less he spoke the more he heard; Why aren't we like that wise old bird?&quot;
       </em>
     </strong>
   </p>
-  <small>- nursery rhyme</small>
+  <small>&mdash; nursery rhyme</small>
 </div>
 ```
 
 **small** is another html formatting element you can use.
 
-> Have you noticed how the character `&#34;` renders on the page?
+> Have you noticed how the character `&mdash;` renders on the page?
 
 ### mailto links `<a>`
 
@@ -323,7 +348,7 @@ The difference between links and mailto links, is the content defined in the **h
 
 > What happens when you click the first link?
 
-> What happens when you click the second link?
+> What happens when you click the second link? How is it different?
 
 > What happens when you add `&body=Owls are amazing` to the second link?
 
