Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dowusubekoe-dev/github-docs-example
https://github.com/dowusubekoe-dev/github-docs-example
Last synced: 8 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/dowusubekoe-dev/github-docs-example
- Owner: dowusubekoe-dev
- License: apache-2.0
- Created: 2023-09-17T00:23:46.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-22T11:19:54.000Z (over 1 year ago)
- Last Synced: 2024-11-17T16:12:38.466Z (2 months ago)
- Size: 103 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
```ruby
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}"
```
Good Cloud Engineers use codeblocks for both Code and Errors that appear in the console.
```bash
Traceback (most recent call last):
2: from /usr/bin/irb:23:in ''
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]](#external-references)
- [x] 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:` | :cloud: |
| Thumb | `:thumbsup:` | :thumbsup: |
## Step 5 - Github Flavored Support Tables
You can use the following markdown format to create tables:
```markdown
| 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]](#external-references)
- 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.
> **[!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
- [Github Flavored Markdown Spec](https://github.github.com/gfm)
- [Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#quoting-text)
- [GFM - Tasks Lists](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#task-lists) [1]
- [GTM - Emoji Cheatsheet](https://github.com/ikatyang/emoji-cheat-sheet)
- [GFM - Tables Extensions](https://github.github.com/gfm/#tables-extension-) [2]