Gist-Blog-Template.md

AJ's Blog Template (ex: Markdown Cheat Sheet)

Markdown is a standardized format for creating web pages and documentation, modeled after the way that people stylize plain-text.

TL;DR

"TL;DR" is a technical term that means "Too Long; Didn't Read". I recommend adding a TL;DR section to all documentation that you create, with the most concise instructions, without much or any explanation, as a quick copy-and-paste or quick-reference example.

People who are just dropping by for a quick answer (including your future self) LOVE this.

Symbol	Usage
#	#### hash, For bold headings
**	double star, For bold
_	underscore, For Italics
-	- dash, For lists
1.	1. For numbered lists

Overview

It's generally a good idea to have an "Overview" or "Table of Contents" section where you list out the other sections. I recommend using a bulleted list, with links to the other sections.

• General Don'ts
• General Dos
• Breaking Rules

Don'ts

Technical writing is nothing like what you learned in school, nor what you see on buzzfeed. The goal should be to communicate much, with very little. For example, here are some don'ts:

• Don't write long paragraphs
• Don't speak in third person (a little personally is good)
• Don't show off

People don't read text, they scan, so make good use of bulleted lists, or numbered lists.

Dos

Write short, 2-3 sentence paragraphs.

• Use bulleted lists where possible
• Take LOTS of screen shots (and recordings)
  • Remember: <ctrl> + <shift> + 5
  • (lists can have images too)
• Use inline blocks for key words in a sentence, but use code blocks for full lines of code

  # here's a bash comment, inside of a list
  # Note: I used 4 SPACES to indent the code at the same level as the list

• Use simple words (the fewer syllables, the better - "3rd grader" words)

Break the Rules

Learn the rules so tha you know when to break them.

Since you're the number 1 audience, you gotta do what works for you most of all. But in learning what works well in general, you'll likely make things easier for yourself.

See Also

It's a good idea to have a "See Also" or "Reference" section where you give credit to sources from which you've learned (especially if you've borrowed material), as well as further reading for people that want to learn more.

Interactive Tutorial

• https://commonmark.org/help/tutorial/

Popular Cheat Sheets

• https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf (abbreviated from [Mastering Markdown](- https://guides.github.com/features/mastering-markdown/))
• https://www.markdownguide.org/cheat-sheet/ (abbreviated from Markdown Guide Basic Syntax)
• https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Interactive (live-preview) Editors

• StackEdit.io
• VSCode Markdown Preview
• Dropbox Paper

homework.md

Homework

Your homework is to create a Markdown Cheat Sheet web page, using this as a template. This cheat sheet is to help you. It will also make for a nice portfolio item.

Your homework is to use Markdown to create a shareable Markdown Cheat Sheet that you will use to teach someone else.

Create a Github Gist web page with the following:

1. A file named something similar to Markdown-Cheatsheet.md
2. A large header with your web page's title
3. A background image that looks at least somewhat related
   • try a Google Image search for "markdown background"
   • to get the URL of an image:
     • (on Mac) use a two-finger click on the image
     • (on Windows) right click on the image
     • select Copy Image Address
4. A blockquote with a 1-3 sentence description of Markdown, in your own words
5. A TL;DR section with a quick reference table
6. A few other sections (perhaps about lists or text formatting or links, etc)

Once you've completed your cheat sheet, make sure that your Gist is public (or click the Make Public button) and then share a link to your Markdown cheat sheet with someone you already know - a friend, parent, sibling, co-worker, whoever.

The goal is to see if they can understand it.

Bonus Assignment 1

Participate on Stack Overflow.

1. Go to Stackoverflow.com
2. Search for "Github Markdown"
3. Sort by Newest
4. Participate
   • Option A: Take the role of a Markdown expert
     • click through several questions and try to find a question that you can answer - which may require doing more research
     • since the questions people are asking may be too complex or too vague, or there may not be enough questions available to answer, this may not be possible - but try anyway
   • Option B: Ask a question about Markdown
     • Search Stackoverflow to see if there is an answer to your question
     • Your question might be a "stupid question", and someone may even make a rude comment or downvote your question - it doesn't matter, ask anyway
     • Update your Cheat Sheet with the new information

Bonus Assignment 2

Give a 10-minute "lightning talk" at a meetup.

Go on meetup.com

1. Make sure that you have "Group" selected, NOT "Calendar"
2. Search for nearby meetup groups, I'd suggest that you look for:
   • Golang
   • Flutter
   • Rust
   • Julia
   • Linux
   • or just genericly for Developer
3. Contact the host, let them know that you’re new to software and that your mentor suggested that you ask to give a 10 minute lightning talk on Markdown, and ask if they would be willing to let you present (online or in person). You may need to contact multiple hosts.

Believe it or not, having completed the primary homework assignment, you're actually more qualified in Markdown that most software developers. By the time that there’s a meetup, having used it several times in this course, you’ll truly be an expert.

Note: Markdown is used for documentation for EVERY programming language, so there are VERY MANY people who could benefit from your presentation. Meetups are usually very friendly, and this will actually be a benefit to those attending.