learn-co-curriculum / your-overview Goto Github PK

#Overview

Let's start with the overview, which is also what every Readme should start with as well. This is usually a 1-2 sentence summary of what the lesson will cover. Like the rest of your writing, it should have a friendly, conversational, and assuring tone.

For both students and instructors, this will give them a quick, brief idea of the lesson without having to read the whole text.

Let's take a look at a not-so-great overview:

AngularJS (commonly referred to as just "Angular") is an open-source framework released in 2009, being mainly maintained by Google as well as a massive community of developers.

It aims to solve the problems faced when creating single page applications, implementing a MVVM pattern to separate presentation and business logic.

It’s pretty dry and not friendly. It also uses what we call “big words” that students may have never heard before and so might be overwhelming to them.

How we reworked this:

In this lesson we're going to be looking into AngularJS (commonly referred to as just "Angular"), an open-source framework that was released in 2009. It is currently being mainly maintained by Google as well as a massive community of developers.

It aims to solve the problems faced when creating single page applications - we'll talk all about them shortly.

Notice now that we use the first-person plural (“we”) and how this humanizes the lesson. While “single page applications” is a phrase that students might also not have heard about, this time it’s something that we’ve now told the student that we’re going to be covering soon.

Let's look at another not-so-great overview:

There are some core concepts that every Angular developer will need to familiarise themselves with. This will teach you the core concepts that you will be using in every Angular application you make.

This isn’t technically difficult, but it’s repetitive and reads pretty impersonally.

How we reworked this:

In this lesson, we are going to look at the core concepts that we will use in every Angular application. Some will be familiar to you, however some may seem a bit strange. Don't worry if they take time to sink in!

Using first-person plural (“we”) again gives a friendly tone, and the second sentence assures students that it's ok if everything they're about to read might not make total sense. This is something that you can use especially in lessons that are earlier on in any track.

Here’s another example of an overview that’s different from the above, but also works in its own way. This is from our Ruby on Rails curriculum.

ActiveRecord associations are an iconic Rails feature. They allow developers to work with complex networks of related models without having to write a single line of SQL--as long as all of the names line up!

This sets the stage for why what we’re about to discuss is important, is brief, and the technical terms that they discuss- “related models” and “SQL”- are concepts that students are already familiar with.

Here’s one final example which is also taken from our Ruby on Rails curriculum:

Now that we know Rails automatically performs validations defined on models, let's use this information to help users fix typos or other problems in their form submissions.

At this point, we'll be covering step two of the following flow: User fills out the form and hits "Submit", transmitting the form data via a POST request. The controller sees that validations have failed, and re-renders the form. The view displays the errors to the user.

Here we start with something the student has already learned and connects it to the content that we’re about to cover. It also puts this information in the larger context of a flow, so while this is a longer overview, this works because it’s still accessible, uses terms that the student already knows, and is conversational.

View Overview on Learn.co and start learning to code for free.