CTP Hackathon:

Documentation Workshop:

A Guide to understanding why documentation is so important in software development, and how to create really intuitive, informative, visually vibrant, and easy to understand README's using GitHub's flavored Markdown syntax! To ensure more people can contribute to your Open Source projects.

To clone this repository:

$ git clone https://github.com/rehman000/CTP-Hackathon-Documentation-Workshop/

GitHub Markdown Cheat sheet:

Welcome Hackers!

To get started I want this to be an interactive excercise where you can reference, apply and pactice the Markdown syntax seen in the Cheat Sheet above.

To begin this activity fork this repository!

Challenge 1: Edit these lines such that the appropriate tag has the appropriate size!

Change this to an h1 tag

Change this to an h2 tag

Change this to an h3 tag

Change this to an h4 tag

Change this to an h5 tag

Change this to an h6 tag

Challenge 2: Edit these lines such that the items in the list below are ordered!

item 1
item 2
item 3
item 4
item 5
item 6

Challenge 3: Edit the following lines so that the text below appears: italic

1 Leetcode a day keeps unemployment away. Start finite first, then inductively expand. Focus on your Foundation, frameworks come and go! The best way to learn is to learn by doing, and try to break things, the more you mess around with the code the better your understanding will become!

Challenge 4: Find the hidden image and add it to this page!

(Hint: Check the Images Folder)

Note: You can also embed images like this using URL's instead of the local file location! Insert the URL inside the (Parenthesis) rather than the file location. If your lost go into edit mode to see what I'm referring to!

Challenge 5: Embed an image using an URL but this time use the appropriate HTML < img > tag syntax instead

Recall: The < img > tag in HTML is self closing!

Challenge 6: Add a .gif file to this document:

(Hint: Check the GIFs Folder, look for a file named Challenge_6.gif)

Stretch Challenge:

For those of you who wish to surpass their limits, and go beyond!

The Cheat Sheet might not cover this entirely:

Challenge 7: When inserting Linux or shell commands in a README it is convention to write the line as block element, and place a '$' symbol to let the reader know that this line is a bash terminal/shell command. Make the following line below a block element:

(Hint: Try using the 'tab' key to indent the line)

Ubuntu
```
  sudo apt-get update
```
Arch
```
  sudo pacman -Syu
```

Challenge 8: Add some ASCII Art without it being ruined using Markdown syntax highlighting:

(Hint: 3 back ticks before and 3 back ticks after with a line of spacing on top and bottom before pasting the ascii art!)

You may copy and paste the following ASCII art

(Additional Hint: What is a back tick? It is also known as the '~' tilda key, it is located above the tab key, and below the esc key on modern keybaords! The back tick symbol looks like this: ` )

⢀⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⣠⣤⣶⣶
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⢰⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣧⣀⣀⣾⣿⣿⣿⣿
⣿⣿⣿⣿⣿⡏⠉⠛⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⣿
⣿⣿⣿⣿⣿⣿⠀⠀⠀⠈⠛⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠛⠉⠁⠀⣿
⣿⣿⣿⣿⣿⣿⣧⡀⠀⠀⠀⠀⠙⠿⠿⠿⠻⠿⠿⠟⠿⠛⠉⠀⠀⠀⠀⠀⣸⣿
⣿⣿⣿⣿⣿⣿⣿⣷⣄⠀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⠏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠠⣴⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⡟⠀⠀⢰⣹⡆⠀⠀⠀⠀⠀⠀⣭⣷⠀⠀⠀⠸⣿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠈⠉⠀⠀⠤⠄⠀⠀⠀⠉⠁⠀⠀⠀⠀⢿⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⢾⣿⣷⠀⠀⠀⠀⡠⠤⢄⠀⠀⠀⠠⣿⣿⣷⠀⢸⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⡀⠉⠀⠀⠀⠀⠀⢄⠀⢀⠀⠀⠀⠀⠉⠉⠁⠀⠀⣿⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠈⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢹⣿⣿
⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿

Challenge 9: Proving why Challenge 8 is practical and useful

Task: List the Directory Structure using the same technique from Challenge 8:

On small scale repositories like this it's not such a big deal, but as your project grows over time, and as you get more collaborators onboard, eventually your code base will baloon and it will take of alot of effort and sanity checking to make sure everyone understands the file structure of your project! Thankfully the community has built tools like tree. Tree is a recursive directory listing program that produces a depth indented listing of files it cam be installed on Mac OS X, Windows (WSL), and Linux.

How tree works:

Here is the file structure for this repository make this into a block element so it doesn't look as messy:

.
├── Images
│   ├── CTP_Logo.png
│   ├── MERN Stack Image.jpg
│   
├── GIFs
│   ├── Tree.gif
|   ├── Stretch Challenge Completed.gif
|   ├── Challenge_6.gif
|

Challenge 10: Make this repository your own!

Add your own code in this repository and try to document your own code. Make sure to include any dependencies, and list the input parameters for each function and the return value of the corresponding function. You can organize this information in any way you see fit. Just make sure to assume the reader is a complete beginner, and has no idea what your code does, as such your README should have the most critical information here, in a visually appealing way that is easy to follow and understand.

Some extra stuff! (for web development)

Okay you've made an awesome Web development project with your team in CTP, now what? Well you need to pick a License! And if you plan to deploy the app and use any CI/CD tools you might need to use these cool markdown stickers!

Travis CI:

The build status is currently set as unknown but that is because we're not actually using Travis CI on this repository!

Some Common Open Source Licenses:

This is a modification made to this remote repo!

Congratulations!

You've completed the stretch guantlet, and used this workshop as an opportunity to expand your horizons!

Here are additional resources you can visit if you ever need to reference anything aside from this repository! :)

https://guides.github.com/features/mastering-markdown/

rehman000 / ctp-hackathon-documentation-workshop Goto Github PK

ctp-hackathon-documentation-workshop's Introduction