title | slug |
---|---|
Writing Content |
writing-content |
Each tutorial is going to be different in terms of how it's broken up, what the content looks like, etc. But with that, there should be some consistencies that exist within every chapter of a tutorial. The following sections outline specific sections and general concepts to include with every tutorial.
Make sure to bold new vocab/terminology as well as underline key phrases in the definition of the term.
New ideas should always be explained assuming 0 previous knowledge of the idea, and the bare minimum in background knowledge required for the new idea.
After the intro/overview chapter, the tutorial should continue with the core content. Longer chapters should be broken up into multiple chapters.
Each h1
header (headers created with a single #
) will create a new tutorial step (with it's own "Mark As Complete" button). Make sure each step makes sense as a step. All the content in a step should be related but short enough to be digestible.
Make sure to utilize the action highlight boxes to help break up just staring at walls of text:
- Action: for when they need to do something (write/copy code, run terminal command, etc.)
- Solution: for when you want to hide/show a solution
- Challenge: extra for experts, tasks for students who want to go the extra mile
- Info: for adding non-essential information to a concept/idea/function/etc. _ Quote: for adding quotes
You are more than likely going to have times where you have students revisit a file/function in your tutorial after they initially wrote it. When doing so, make sure to be explicit on what code is staying the same, and what code will be changing. You can do this a variety of ways:
- Use Comments: Leave comments signifying what code is changing, and unchanged lines should remain the same with no comments.
- Use the [bold] tag See the
Syntax Formatting Within Code Blocks
section in the first chapter (P00
) to see how to use these to highlight changed code - Use ellipsis to skip unchanged code Start with the top of the file, then place some ellipsis to show that we're skipping down to just the area of the code that's changing. For example:
# app.py
...
# This is the function that changed‰
def foo():
x = "bar"
print(x)
Make sure to remind students of their user stories, and which ones they're going to be working on by bolding them, and then cross off the ones that have been completed.
If possible, try to break down the user story as well into sub-tasks, which can just be sub-bullets in the list
This should be one of the first sections of a tutorial. An example is below for a student who has finished the first 4 user stories and is about to start the 5th in this chapter:
Create a postShow all postsShow one postComment on posts- Create subreddits
- Add a
subreddit
attribute to our post resource - Navigate to view all the posts of the same subreddit
- Add a
- Sign up and Login
- Associate posts and comments with their author
- Make comments on comments
- Vote a post up or down
Make a specific section in each applicable chapter for students to see what the progress so far looks like. This is where screenshots of the app in progress should be for students to easily jump to if needed.
Students need to be prompted to commit their work and push to GitHub. This should happen at a minimum of once per chapter, but feel free to include more if you feel it is needed.
The following can be used for each section of a chapter. Remember to update the commit message and REPO-NAME to something relevant, and to remove the \
:
# Now Commit
>[action]
>
\```bash
$ git add .
$ git commit -m 'Commit Message'
$ git push
\```
Be sure to alert students at the end of a chapter if they've achieved (or even worked on) a Learning Outcome. Can be a simple affirmation such as the following (with the marked parts replaced):
Great job! By doing this action
, you've successfully COMPLETED_LEARNING_OUTCOME_1
!
Make sure to bold the Learning Outcome when doing this.
Try to include code tests as either 1-2 chapters in the tutorial, or as sub-sections throughout chapters. These can be unit tests, integration tests, etc. We just want to ingrain testing as a best practice into students, and our tutorials should reflect that.
Check out the Rotten Potatoes Testing Chapter for an example of this in action.
This should be an action box towards the end of the last chapter asking the students to relate this to class material. Be sure to mention class learning outcomes, or lesson topics so they have a reference to the course.
Create a feedback form from this template: make.sc/tutorial-feedback-template. Please copy it into the correct sub-folder(s) under the Curriculum Feedback drive. Fill out the items on the form, and then create this subsection in the last chapter of your tutorial:
# Feedback and Review - 2 minutes
**We promise this won't take longer than 2 minutes!**
Please take a moment to rate your understanding of the learning outcomes from this tutorial, and how we can improve it via our [tutorial feedback form](LINK_TO_YOUR_FORM)
This allows us to get feedback on how well the students are grasping the learning outcomes, and tells us where we can improve the tutorial experience.