/Terraform-Bootcamp-Documentation

Apache License 2.0Apache-2.0

Writing Good Documentation

Weekly Journals

Step 1 - Using Codeblocks

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

Why? becuase it allows others to copy and paste their code to replicate or research isssues.

  • In order to create codeblocks in markdown you need to use three backticks. (```)

Print ("Hello, World!")
  • When you can you should attempt to apply syntax highlighting to you codeblocks.
Print ("Hello, World!")
  • Good engineers use codeblocks for errors that appear in the console.
Traceback (most recent call last):
File "example.py", line 4, in <module>
result = divide(10, 0)
File "example.py", line 2, in divide
return a / b
ZeroDivisionError: division by zero

Here is an example of using a codeblock for an error that appears in bash.

Step 2 - Use Github Flavored Markdown Task Lists

Github extends markdown to have a list where you can check off items. Using lists can show that your doing the work and people can see your making an effort making it easier to help you. [2]

  • Finish step 1 🎉 [3]
  • Finish step 2 🎉
  • Finish step 3 🎉

Step 3 - Use Emojis (Optional)

Github Flavored Markdown (GFM) supports emoji shortcodes. Here are some examples: [4]

Name Shortcode Emoji
Cloud :cloud: ☁️

References

A good way to write documentation is to always site your references if you have ever used some.