Fn Tutorials Guide

This is a guide to creating a tutorial for the FN project.

Before You Begin

Background

The goal of this guide is describe some of the techniques and conventions we use to create Fn tutorials. We want to achieve some consistency in our tutorials but at the same time keep things simple.

Note: As a bonus this guide it written using our tutorial template (provided at the end of this guide) as an example of its use.

Prerequisites

• An editor for creating Markdown.

Initial Setup

Follow these steps.

1. Create a directory for your tutorial in the repo.
2. In the directory create an images directory.
3. Copy the userinput.png into that directory.
4. Create a README.md file using the tutorial template included at the end of this document.
5. Customize the titles, sections, and section titles to meet your needs.

Formatting

There are a few markdown formatting styles and techniques we use in our tutorials. The Jekyll theme relies on these to build HTML pages.

Titles and Sections

The tutorial JavaScript navigation relies on your Markdown headers having a hierarchy. Thus, your headers should have a structure like: h1 (#) --> h2 (##) --> h3 (###). Nav is built based on this hierarchy. Without it, the left nav will not work properly.

Here are examples of good tutorial structures.

h1 -> h2
h1 -> h2 -> h3

# My title
## My steps
### My sub-steps

Here are examples of bad tutorial structures.

h1 -> h1 -> h1
h1 -> h3

# Title
# Step 1
# Step 2

Try to use action verbs telling the learner what to do in section titles. For example, "Start Fn Server", "Create your Function".

User Actions and Graphic

Each time you want the user to do something precede that step with an icon followed by the command with the following format. For example:

![User Input Icon](https://github.com/fnproject/tutorials/raw/master/Introduction/images/userinput.png)

>```sh
>export ENV_VAR=VALUE
>```

export ENV_VAR=VALUE

The icon should be on a line by itself that precedes the command. The command is contained in a code block within a blockquote. The command is syntax highlighted and indented from the left margin.

If you don't want syntax highlighting for your command, you can use simple syntax. For example:

![User Input Icon](https://github.com/fnproject/tutorials/raw/master/Introduction/images/userinput.png)

>`fn start`

fn start

This approach saves some typing and still looks good.

Note: Jekyll uses the Rouge Syntax Highlighter for code blocks. See that documentation for languages supported and which letter abbreviations to use for your code.

Tutorial Template

Here is a template for creating a tutorial. Note the only required elements are a "Title" and at least one "Step Section". The "Before you Begin" and "Learn More" sections are recommended but not required.

# Tutorial Title (Required)
Each tutorial must have a title. 

## Before you Begin (Recommended)
Provides you the why about this tutorial.  Also covers any  required setup to do the tutorial.

### Background (Optional)
Provides a information about what the tutorial covers and what you will learn. Covers the why of the tutorial.

### Prerequisites(Optional)
Spells out any activities or tools that are required before starting the tutorial.

## Section (At least 1 Required)
You must have at least 1 step/section for a tutorial. You do not need to number the steps.

## Additional Section (Option)
Create as many sections as you need. Use or don't use Section steps (### and ####) as you need.

### Section Step (Optional)
One step in this section.

### Section Step (Optional)
One step in this section.

#### Section Sub-Step
Sub-step if needed.

#### Section Sub-Step
Sub-step if needed.

## Learn More (Recommended)
Links to resources where learners could go to learn more about this topic.

* Link
* Link
* Link

Learn More

• Fn Project
• Fn Project Tutorials