/github-docs-example

Apache License 2.0Apache-2.0

Writing Good Documentation

Step 1 - Using Codeblocks

Codeblocks in markdown makes it very easy for tech people to copy, paste, share code. A good Cloud Engineer 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 backticks (`)
  • Not to be confused with single quotation (')
def factorial(n)
  if n <= 1
    return 1
  else
    return n * factorial(n - 1)
  end
end

puts "Enter a number to calculate its factorial:"
number = gets.chomp.to_i

result = factorial(number)
puts "The factorial of #{number} is #{result}"
  • When you can, you should attempt to apply syntax highlighting to your codeblocks
def factorial(n)
  if n <= 1
    return 1
  else
    return n * factorial(n - 1)
  end
end

puts "Enter a number to calculate its factorial:"
number = gets.chomp.to_i

result = factorial(number)
puts "The factorial of #{number} is #{result}"

Terraform icon

Altered image

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 codeblock for an error that appears in bash.

Step 3 - Use Github Flavored Markdown Task Lists

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

  • Final Step 1
  • Final Step 2
  • Final Step 3

Step 4 - Use Emojis (Optional)

Github Flavored Markdown (GFM) upports emoji shortcodes. Here is some examples: :cloud:

Name Shortcode Emoji
Cloud :cloud: ☁️
Thumb :thumbsup: 👍

Step 5 - Github Flavored Support Tables

You can use the following markdown format to create tables:

| Name | Shortcode | Emoji |
| --- | --- |  --- |
| Cloud | `:cloud:` | :cloud: |
| Thumb | `:thumbsup:` | :thumbsup: |

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

  • Make note of where the backtick button is located.
  • It should appear above the tab key,
  • but it may vary based on your keyboard layout or type.

Photo of Terraform

[!NOTE] Highlights information that users should take into account, even when skimming.

[!IMPORTANT] Crucial information necessary for users to succeed.

[!WARNING] Critical content demanding immediate user attention due to potential risks.

External References