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.
$ git clone https://github.com/rehman000/CTP-Hackathon-Documentation-Workshop/
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.
- item 1
- item 2
- item 3
- item 4
- item 5
- item 6
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!
(Hint: Check the GIFs Folder, look for a file named Challenge_6.gif)
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
(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
PASTE YOUR ASCII ART HERE!
Read and delete the line below when your editing it is not needed:
$ echo One practical benefit of this is that when I have a really really long bash or shell command, and it might take up alot of lines, and it might be confusing to understand how to use it! But by making it a block element you can scroll through this line! :D
(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: ` )
- 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 can be installed on Mac OS X, Windows (WSL), and Linux.
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
|
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.
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/
