Giter VIP home page Giter VIP logo

github-docs-example's Introduction

Writing Good Documentation

Step 1 - Using Codeblocks.

Codeblocks in markdown make 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 ceate codeblocks in makdown you need to use three backticks (`)
  • Not to be confused with single quotation '
class Person
  attr_accessor :name, :age

  # Constructor method
  def initialize(name, age)
    @name = name
    @age = age
  end

  # Instance method to introduce the person
  def introduce
    puts "Hello, my name is #{@name} and I am #{@age} years old."
  end

  # Instance method to check if person is an adult
  def adult?
    @age >= 18
  end
end

# Create a new person instance
john = Person.new("John", 25)

# Introduce the person
john.introduce

# Check if the person is an adult
if john.adult?
  puts "#{john.name} is an adult."
else
  puts "#{john.name} is not an adult."
end
  • When you can you should attempt to apply syntax higlighting to your codeblocks
class Person
  attr_accessor :name, :age

  # Constructor method
  def initialize(name, age)
    @name = name
    @age = age
  end

  # Instance method to introduce the person
  def introduce
    puts "Hello, my name is #{@name} and I am #{@age} years old."
  end

  # Instance method to check if person is an adult
  def adult?
    @age >= 18
  end
end

# Create a new person instance
john = Person.new("John", 25)

# Introduce the person
john.introduce

# Check if the person is an adult
if john.adult?
  puts "#{john.name} is an adult."
else
  puts "#{john.name} is not an adult."
end

Just a random downsized picture of showing an image of an Octocat smiling and raising a tentacle

Good Cloud Engineers use codeblocks for both Code and Errors that appear in the console.

Traceback (most recent call list):
  2: from /us/bin/irb:23:in `<main>'
  1: from (irb):1
RunetimeError: This is a custom error message

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

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 take a photo with your phone.

To take screenshots both on macOS and Windows, you can use the following hotkeys:

On macOS (formerly Mac OS X):

  1. Entire Screen:

    • Command (⌘) + Shift + 3
  2. Selected Portion:

    • Command (⌘) + Shift + 4, then drag to select the area you want to capture.
  3. Window:

    • Command (⌘) + Shift + 4, then press Spacebar. Click the window you want to capture.
  4. Entire Screen and save to clipboard (instead of saving to a file):

    • Command (⌘) + Control + Shift + 3
  5. Selected Portion and save to clipboard:

    • Command (⌘) + Control + Shift + 4, then drag to select the area.

By default, screenshots on macOS are saved to the desktop with a name like "Screen Shot YYYY-MM-DD at HH.MM.SS AM/PM."

On Windows:

  1. Entire Screen:

    • Print Screen (often labeled as PrtScn)
  2. Active Window:

    • Alt + Print Screen
  3. Selected Portion (Windows 10 and later):

    • Windows + Shift + S (This will open up a snipping tool interface allowing you to select a portion of the screen. The screenshot will be saved to your clipboard.)
  4. Using Snipping Tool:

    • This isn't a hotkey per se, but Windows has a built-in app called Snipping Tool which allows for various screenshot options. You can search for it in the Start menu.
  5. Save the Entire Screen directly as a file (Windows 8 and later):

    • Windows + Print Screen (The screenshot will be saved in the "Screenshots" folder inside the "Pictures" library.)

Remember, after taking a screenshot, you can paste it directly into most applications (like Paint or Word) using the paste function (Command/Control + V).

Step 3 - Use gitHub Flavoured Markdown Task Lists

GitHub extends Markdown to have a list where you can check of items. [1]

  • Finish Step 1
  • Finish Step 2
  • Finish Step 3

Step 4 - Use Emojis (optional)

GitHub Flavored Markdown (GFM) supports emoji shortcodes. Here are some examples:

Name Shortcode Emoji
Cloud :cloud: ☁️
Cloud :cloud_with_lightning: 🌩️

Step 5 - How to create a table

You can use the following markdown foirmat to create tables:

| Name | Shortcode | Emoji | 
| --- | --- | --- |
| Cloud | `:cloud:` | :cloud: |
| Cloud | `:cloud_with_lightning:` | :cloud_with_lightning: |

GFM extends the functionality of markdown tables to provide more alignment an tabel cell formatinng options. [2]

Secret Window Hidden Garden

External References

github-docs-example's People

Contributors

virbeaver avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.