blackzu/github-docs-example

Writing Good Documentation

Step 1 - Using Codeblocks

Codeblocks in markdown helps to do a very nice documentation for code and comments associated with it.

Anything that is needed as a part of your project repo README, can be nicely done with the help of codeblocks in Github Flavoured Markdown.

A good Cloud Engineer makes use of Codeblocks to document their piece of work.

• In order to create codeblocks you need to use 3 backticks(```) that comes with the tilde button in your keyboard.
• Do not confuse this with quotations('')

#Solution.py
def add_numbers(a, b):
    return a + b
    
print(add_numbers(5, 3))  # Output: 8

• A good Cloud Engineer not only documents blocks of code but also documents the errors that they come across

Traceback (most recent call last):
  File "Solution.py", line 3, in <module>
    result = numerator / denominator
ZeroDivisionError: division by zero

Step 2 - Todo List

• Write goooooooooooooood documentation
• Update Github
• Learn in Public

Step 3 - Tables & Emojis

Name	Shortcode	Emoji
Cloud	:cloud:	☁️
Smile	:smile:	😄
Office	:office:	🏢
Coffee	:coffee:	☕

Step 4 - Anchor

Read this to get a job in Cloud right now

References

• GitHub Flavored Markdown Spec¹
• Basic syntax and formatting²
• Codeblocks³
• Github Markdown Editor & GFM⁴
• GFM Emoji Cheatsheet⁵