Treating documentation like code improves collaboration, version control, and efficiency for technical writers. Here’s a beginner-friendly guide to getting started with Git & GitHub—even if you don’t know how to code!
🔹 What is Docs as Code?
Docs as Code is a documentation approach where writers use the same tools and workflows as software developers to create, manage, and publish content.
✅ Version control: Multiple contributors can work on a document while tracking changes seamlessly.
✅ Collaboration: Technical writers and developers can edit docs together in a shared space.
✅ Automation: Docs can be updated and deployed alongside software releases.
📌 Git and GitHub are two of the most popular tools for Docs as Code, and that’s what we’ll focus on today!
💡 Quick Tip: If you’re new to GitHub, you can create a free account—but note that free accounts do not allow private repositories. Avoid working on any sensitive documents unless you opt for a paid plan.
🔹 Key Principles of Docs as Code
✔️ Plain Text Formats – Use Markdown, AsciiDoc, or reStructuredText instead of proprietary tools.
✔️ Version Control with Git – Track changes, collaborate, and revert to previous versions if needed.
✔️ Information Architecture – Documents are structured and concise.
✔️ Collaboration with Developers – Store documentation in GitHub so both writers and devs can access, edit, and suggest improvements.
📌 Key takeaway: Treating docs like code ensures consistency, transparency, and seamless collaboration between writers and developers.
🔹 Why Technical Writers Should Learn Git & GitHub
If developers use Git for code, why should technical writers use it for docs?
✔️ Prevents content loss – No more “Who edited this last?” nightmares.
✔️ Branching & merging – Work on updates without disrupting live content.
✔️ Review workflows improve accuracy – Request feedback through GitHub pull requests.
💡 Example: Instead of editing a shared doc with multiple versions floating around, you create a new branch, make updates, and submit a pull request. Team members can review, provide feedback, and merge changes back into the main document—all while tracking every edit!
🔹 Getting Started: A Beginner’s Guide to Docs as Code
👩💻 Step 1: Learn Basic Git Commands
Start with these core Git commands:
✔️ git clone – Copy an existing project to your local machine.
✔️ git commit – Save changes locally.
✔️ git push – Upload changes to GitHub.
✔️ git pull – Download the latest updates from the repository.
✔️ git merge – Combine changes from different branches.
💡 Where to Learn? GitHub offers free tutorials, Udemy has a great course: Git and GitHub for Writers (created by Peter Gruenbaum) and check out this free Git command line tool!
📁 Step 2: Store Documentation in a GitHub Repository
Create a repository to manage documentation like developers manage code. This allows you to:
✔️ Track every change.
✔️ Collaborate with a team.
✔️ Automate publishing workflows.
🛠 Step 3: Use Markdown for Writing
✔️ There are more options to use but Markdown is lightweight, intuitive, and widely used—perfect for Docs as Code!
✔️ If you’ve worked with HTML or XML, you’ll pick it up quickly -and if not, it’s easy to learn!
✔️ Need a plain text editor? Notepad++ (Windows) is a great free option.
📌 Pro Tip: Start small—try managing just one document in GitHub before diving into full automation!
🔹 Overcoming Common Docs as Code Challenges
🚩 “I’m not a developer—Git is intimidating!” → Start with a personal repo and basic commands.
🚩 “What if I break something?” → Git tracks every change, so you can always roll back.
💡 Reminder: Every tech writer learning Git starts as a beginner—don’t be afraid to experiment!
🔹 Final Thoughts: The Future of Docs as Code
✔️ Docs as Code is becoming the industry standard.
✔️ Learning Git future-proofs your career.
✔️ Embracing developer workflows makes technical writers more valuable.
💬 What are your thoughts on Docs as Code? Have you used Git or GitHub for documentation? Drop your experience in the comments! ⬇️
Pen and Polish 