Introduction
In Part 1, we successfully moved the resume from a local editor to a live URL. But an empty repository is like a house without a front door, functional, yet inaccessible to those looking in. In this second installment, we’re going back into the terminal to master the art of the README.
I’ll show you how to turn a folder of code into a polished, technical portfolio that speaks for itself. Whether you’re a Cloud aspirant or a DevOps enthusiast, your documentation is your handshake. Let’s make it count.
Step 1: Navigating and Initializing the README
In the previous guide, we set up the environment. Now, we return to the terminal to add the "front door" of our project, that is the the README.md file.
Changing Directory: We start by using cd ~/Desktop/website to ensure we are working inside the correct project folder.
Creating the File: The touch README.md command is used to generate a blank Markdown file. Using the .md extension is crucial as it tells GitHub to render this as a formatted document rather than just plain text.
Opening the Editor: To add content, we use the vi README.md command. This opens the Vi text editor directly in the terminal, it's a lightweight, powerful tool that every Cloud and DevOps professional should be comfortable using.
Step 2: Inspecting and Verifying Content
Once I’ve finished editing in Vi, it’s best practice to verify that your data was saved exactly how you intended.
We use cat README.md to display the entire contents of the file directly in the terminal. This check ensures there are no typos or formatting errors in our Markdown syntax before we push.
The output shows a structured, professional layout:
Project Title: Using # for a clear H1 heading.
Live Links: Providing immediate access to the hosted resume.
Visual Elements: Using emojis (🚀, 🛠️, 📖) to make the documentation modern and readable.
Technical Milestones: A numbered list summarizing the core achievements of the project.
Command Reference: Using backticks (`) for code blocks, creating a "cheat sheet" for anyone who forks the repository.
Step 3: The Version Control Lifecycle (Stage & Commit)
In this step, we move our new documentation through the Git lifecycle. It’s not enough to just create the file, we have to tell Git to track it.
git status (The Pulse Check): Before doing anything, I ran git status. You can see README.md highlighted in red under Untracked files. This confirms that Git sees a new file but isn't yet managing it.
git add README.md (Staging): This command moves the file into the staging area. The terminal warning about LF will be replaced by CRLF is a common occurrence in Git Bash on Windows, it’s just Git managing how line endings are handled between different operating systems.
git commit (The Snapshot): By running git commit -m "add README with project overview and commands", we officially record the change. The output "1 file changed, 30 insertions" serves as a receipt, confirming that our 30 lines of professional documentation are now part of the project's history.
Step 4: The Final Push (Syncing to the Cloud)
This is the bridge between our local work and our public profile.
git push origin master: This command tells Git to take the committed changes (the new README) and upload them to the origin (GitHub) on the master branch.
"Enumerating objects: 4, done": Git is gathering the files you changed.
"Writing objects... 1.19 KiB": This confirms the actual data transfer.
The Confirmation: The line bb98894..e6d1410 master -> master is the technical "all clear." It shows your local branch is now perfectly synced with GitHub.
Step 5: Configuring the Global Gateway (GitHub Pages)
Once the code is safely in the cloud, you have to tell GitHub how to serve it to the public.
Navigating to the Settings > Pages tab is where the hosting magic happens.
I set the source to Deploy from a branch and selected the master branch and / (root) folder. This tells the GitHub server to look for our index.html file exactly where we saved it.
Once saved, GitHub generates a custom URL (e.g., https://rahimahisah17.github.io/Git-Basics101/).
Seeing that "Your site is live" message is the ultimate green light for a developer!
Conclusion
Documentation is the bridge between writing code and building a career. A project without a README is just a folder, a project with a README is a story of your technical journey.
This article was originally published by DEV Community and written by Rahimah Sulayman.
Read original article on DEV Community