Skip to content

Latest commit

 

History

History
199 lines (148 loc) · 7.2 KB

sample.md

File metadata and controls

199 lines (148 loc) · 7.2 KB
Raw

summary: This is a sample Snowflake Guide id: sample categories: undefined environments: web status: Hidden feedback link: https://github.com/Snowflake-Labs/sfguides/issues tags: Getting Started, Data Science, Data Engineering, Twitter authors: Snowflake

Snowflake Guide Template

Overview

Duration: 1

Please use this markdown file as a template for writing your own Snowflake Quickstarts. This example guide has elements that you will use when writing your own quickstarts, including: code snippet highlighting, downloading files, inserting photos, and more.

It is important to include on the first page of your guide the following sections: Prerequisites, What you'll learn, What you'll need, and What you'll build. Remember, part of the purpose of a Snowflake Guide is that the reader will have built something by the end of the tutorial; this means that actual code needs to be included (not just pseudo-code or concepts).

The rest of this Snowflake Guide explains the steps of writing your own guide.

Prerequisites

  • Familiarity with Markdown syntax

What You’ll Learn

  • how to set the metadata for a guide (category, author, id, etc)
  • how to set the amount of time each slide will take to finish
  • how to include code snippets
  • how to hyperlink items
  • how to include images

What You’ll Need

What You’ll Build

  • A Snowflake Guide

Metadata Configuration

Duration: 2

It is important to set the correct metadata for your Snowflake Guide. The metadata contains all the information required for listing and publishing your guide and includes the following:

  • summary: This is a sample Snowflake Guide
    • This should be a short, 1 sentence description of your guide. This will be visible on the main landing page.
  • id: sample
    • make sure to match the id here with the name of the file, all one word.
  • categories: data-science
    • You can have multiple categories, but the first one listed is used for the icon.
  • environments: web
    • web is default. If this will be published for a specific event or conference, include it here.
  • status: Published
    • (Draft, Published, Deprecated, Hidden) to indicate the progress and whether the sfguide is ready to be published. Hidden implies the sfguide is for restricted use, should be available only by direct URL, and should not appear on the main landing page.
  • feedback link: https://github.com/Snowflake-Labs/sfguides/issues
  • tags: Getting Started, Data Science, Twitter
    • Add relevant tags to make your sfguide easily found and SEO friendly.
  • authors: Daniel Myers
    • Indicate the author(s) of this specific sfguide.

You can see the source metadata for this guide you are reading now, on the github repo.

Creating a Step

Duration: 2

A single sfguide consists of multiple steps. These steps are defined in Markdown using Header 2 tag ##.

## Step 1 Title
Duration: 3

All the content for the step goes here.

## Step 2 Title
Duration: 1

All the content for the step goes here.

To indicate how long each step will take, set the Duration under the step title (i.e. ##) to an integer. The integers refer to minutes. If you set Duration: 4 then a particular step will take 4 minutes to complete.

The total sfguide completion time is calculated automatically for you and will be displayed on the landing page.

Code Snippets, Info Boxes, and Tables

Duration: 2

Look at the markdown source for this sfguide to see how to use markdown to generate code snippets, info boxes, and download buttons.

JavaScript

{ 
  key1: "string", 
  key2: integer,
  key3: "string"
}

Java

for (statement 1; statement 2; statement 3) {
  // code block to be executed
}

Info Boxes

aside positive

This will appear in a positive info box.

aside negative

This will appear in a negative info box.

Buttons

Youtube - Halsey Playlists

Tables

**The table header**
The table body with two columns

Hyperlinking

Youtube - Halsey Playlists

Images, Videos, and Surveys, and iFrames

Duration: 2

Look at the markdown source for this guide to see how to use markdown to generate these elements.

Images

Puppy

Videos

Videos from youtube can be directly embedded:

Inline Surveys

How do you rate yourself as a user of Snowflake?

Embed an iframe

https://codepen.io/MarioD/embed/Prgeja

Importing markdown files

Duration: 1 <<_imports/sample_import.md>>

Conclusion & Next Steps

Duration: 1

The Conclusion and Next Steps section is one of the most important parts of a guide. This last section helps to sum up all the information the reader has gone through, and in many ways should read like a TLDR summary.

There are three main sub-headers in a Conclusion step:

  1. a general conclusion paragraph (what you are reading now!)
  2. "What We've Covered" section with a bulleted list of things
  3. "Related Resources" with links to various other resources, other guides, docs, videos, GitHub source code, etc.

It's also important to remember that by the time a reader has completed a Guide, the goal is that they have actually built something! Guides teach through hands-on examples -- not just explaining concepts.

What We've Covered

  • creating steps and setting duration
  • adding code snippets
  • embedding images, videos, and surveys
  • importing other markdown files

Related Resources