fsohmoek / github-docs-examples

Writing Good Documentation

Step 1 - Using Codeblocks.

Codeblocks in markdown make it very easy for tech people to copy, paste, share code. A good Cloud Enginner uses Codeblocks whenever possible

Because it allows others to copy and paste their code to replicate or research issues

• In order to create codeblocks in markdown you need to use three blackticks (```)
• Not to be confused with quotation (''')

#!/bin/bash
read -p "Enter a number and hit \"Enter\" " user_number
if [ $user_number -gt 10 ]
then
    echo "The number you entered is greater than 10."
else
    echo "The number you entered is less than or equal to 10."
fi

• When you can you should attempt to apply syntax highlighting to your codeblocks

#!/bin/bash
read -p "Enter a number and hit \"Enter\" " user_number
if [ $user_number -gt 10 ]
then
    echo "The number you entered is greater than 10."
else
    echo "The number you entered is less than or equal to 10."
fi

Good Cloud Engineers use codeblocks for both Code and Errors that appear in the console.

Traceback (most recent call last):
        2: from /usr/bin/irb:23:in `<main>'
        1: from (irb):1
RuntimeError: This is a custom error message

Here is an example of using a codeblocks for an error thaht appears in bash.

When you can always provide a codeblock instead of a screnshot. If you need to take a screenshot make sure it is not a photo from your phone.

There are certain cases where its okay to take photos with your phone. This is when you are showing something like a keyboard, which does not appear on a computer screen. If it render on your computer screen it should be a screenshot

Step 3 - Use GiHub Flavored Markdown Task Lists

Github extends Markdown to have a list where you can check off items. ^[1]

• Finish step 1
• Finish step 2
• Finish Step 3

Step 4 - Use Emojis (Optional)

GitHub Flavored Markdown (GFM) supports emoji shortcodes

Here are some examples:

Name	Shortcode	emoji
Cloud	`:cloud:'	☁️

Step 5 - How to create a table

You can use the following markdown format to create tables.

| Name | Shortcode | emoji|
| --- | --- | ---|
| Cloud | `:cloud:' | ☁️ |
| Cloud with lighting | ':Cloud_with_lighting:` | 🌩️ |

GitHub extends the functionality of Markdown tables to provide more alignment and table cell formatting options. ^[2]

External References

• 
• 
• ^[1]
• 
• ^[2]