Writing Good Documentation

Weekly Journals

• Week 0 Journal

• Week 1 Journal

• Week 2 Journal

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.

• Basic writing and formatting syntax (Github Flavored Markdown) ^[1]

• Github Flavored Markdown - Task List ^[2]

• Github Flavored Markdown - Emoji Cheat Sheet ^[3]

• Github Flavored Markdown - Create a table ^[4]