/github-docs-example

Apache License 2.0Apache-2.0

Writing good documentation

Step 1 - Using codeblocks

Codeblocks in markdown make it very easy for tech people to copy, paste, and share code because it allows otehr to copy and paste their code to replicate or research issues.

  • A good Cloud Engineer uses codeblocks whenever possible. When you can, you should attempt to apply syntax highlighting to your codeblocks, like this:
def factorial(n)
  if n == 0
    return 1
  else
    return n * factorial(n - 1)
  end
end

# Calculate the factorial of 5
result = factorial(5)
puts "Factorial of 5 is #{result}"
  • Make note of where the backtick button is located on your keyboard (it varies depending on your kb layout/region).
dog meme
  • Good Cloud Engineers use codeblocks for both code and code errors that appear on the console. Here is an example of using codeblocks for an error that appears in bash.
$ nonExistentCommand
bash: nonExistentCommand: command not found

This is a random quote:

"I am Beyoncé always" Michael Scott

Step 2 - How to take screenshots

A screenshot is when you capture a part of your screen from your laptop, desktop or phone. This is not to be confused with taking a photo with your phone.

Immediately no 🤚

photo of computer taken with phone

I suggest using Lighshot [1], it works on Windows and Mac. With this tool, you can capture the screen or part of it and save it as an image or paste it on Paint.

Step 3 - Using Github Flavored Task lists

Github extends markdown to have a list where you can check off items.[2]

  • Finish Step 1
  • Finish Step 2
  • Finish Step 3
  • Create more steps 🎉

Step 4 - Using Emojis

Github Flavored Markdown supports emoji shortcodes. Here are some examples:

Name Shortcode Emoji
Smile :smile: 😊
Heart :heart: ❤️
Thumbs Up :+1: 👍
Coffee :coffee: ☕
Cloud :cloud: ☁️

🔒🪟

References