From 554a14f32b07c7bd4bdfd7c0175c37f3f1a8f36b Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 30 Mar 2026 20:58:00 -0500 Subject: [PATCH 1/8] Update root home page, book landing --- _learn/000-docs-as-code-quick-start-guide.md | 248 +++++++++++++++++++ book/index.md | 206 +++++++++++---- index.html | 60 ----- index.md | 171 +++++++++++++ 4 files changed, 573 insertions(+), 112 deletions(-) create mode 100644 _learn/000-docs-as-code-quick-start-guide.md delete mode 100644 index.html create mode 100644 index.md diff --git a/_learn/000-docs-as-code-quick-start-guide.md b/_learn/000-docs-as-code-quick-start-guide.md new file mode 100644 index 0000000..c41a1a6 --- /dev/null +++ b/_learn/000-docs-as-code-quick-start-guide.md @@ -0,0 +1,248 @@ +--- +title: "Docs-as-Code Quick Start Guide" +layout: learn +image: + path: /images/learn/mikecogh-trains.jpg + thumbnail: /images/learn/github-logo400x200.png + caption: "Photo from [Flickr:mikecogh](https://flic.kr/p/pEn3RB)" +--- + +# Docs-as-Code Quick Start Guide + +**Build Your First Modern Documentation Workflow Using GitHub, Markdown, and Automation** + +--- + +## Introduction: Why Documentation Feels Broken + +If you’ve worked in documentation, you’ve probably experienced this: + +* Content lives in Word docs, wikis, or scattered tools +* Developers don’t contribute—or avoid docs entirely +* Publishing updates is slow and manual +* Documentation quickly becomes outdated + +The result? Frustration, inconsistency, and a constant feeling of playing catch-up. + +There’s a better way. + +--- + +## What Is Docs as Code? + +**Docs as Code** is an approach where you create and manage documentation using the same tools and workflows as software development. + +Instead of separate systems, you use: + +* Version control (Git) +* Plain text files (Markdown) +* Collaborative workflows (pull requests) +* Automated publishing (CI/CD) + +This brings documentation into the same ecosystem as your engineering team—making it faster, more collaborative, and more scalable. + +--- + +## What You Can Build with This Guide + +In the next 20–30 minutes, you’ll: + +* Create a documentation repository +* Write content in Markdown +* Make and review changes using pull requests +* Understand how publishing can be automated + +No advanced setup required—just a basic familiarity with Git concepts. + +--- + +## Step 1: Create a Repository + +Start by creating a new repository for your documentation, meaning a folder locally and a repository on a site like GitHub. + +Suggested name: + +``` +docs-example +``` + +This repository holds all your documentation files. + +### Why this matters + +Storing documentation in a repository gives you: + +* Version history +* Collaboration via pull requests +* A single source of truth + +--- + +## Step 2: Add Your First Markdown File + +Create a file called: + +``` +index.md +``` + +Add the following content: + +```markdown +# Welcome to Our Documentation + +This is our first docs-as-code project. + +## Getting Started + +This documentation is written in Markdown and managed in Git. +``` + +### Why Markdown? + +Markdown is: + +* Simple and readable +* Easy to edit +* Widely supported by documentation tools + +It removes formatting friction so you can focus on content. + +--- + +## Step 3: Make a Change Using a Pull Request + +Instead of editing directly on the main branch, create a new branch: + +``` +update-intro +``` + +Edit your file: + +```markdown +This documentation is written in Markdown and managed in Git. + +We use a docs-as-code workflow to collaborate and publish content. +``` + +Now open a pull request. + +### What’s happening here? + +You’ve just: + +* Proposed a change +* Made it visible for review +* Enabled collaboration + +This is the core of docs-as-code. + +--- + +## Step 4: Review and Collaborate + +In a real team, someone would: + +* Review your changes +* Leave comments +* Suggest improvements + +This creates: + +* Higher-quality documentation +* Shared ownership +* Better alignment with engineering + +--- + +## Step 5: Merge and Publish + +Once approved, merge the pull request. + +At this point, your documentation is: + +* Updated +* Versioned +* Ready to publish + +--- + +## Step 6: (Optional) Add a Static Site Generator + +To turn your Markdown into a website, you can use a static site generator like: + +* Jekyll +* Hugo +* Sphinx + +These tools: + +* Convert Markdown into HTML +* Apply themes and navigation +* Create a professional documentation site + +--- + +## Step 7: Automate Publishing + +The final step is automation. + +Using CI/CD, you can: + +* Automatically build your site +* Deploy it when changes are merged +* Keep documentation always up to date + +Now your workflow looks like this: + +**Write → Review → Merge → Publish (automatically)** + +--- + +## What You Just Achieved + +In a short time, you’ve: + +* Created a version-controlled documentation system +* Collaborated using pull requests +* Prepared content for automated publishing + +This is the foundation of docs as code. + +--- + +## Why This Changes Everything + +Compared to traditional documentation, this approach: + +* Reduces bottlenecks +* Improves collaboration with developers +* Enables faster updates +* Scales across teams and products + +Instead of being an afterthought, documentation becomes part of the development process. + +--- + +## What’s Next + +This quick start only scratches the surface. + +In the full book, you’ll learn how to: + +* Design scalable documentation architectures +* Choose the right tools and platforms +* Implement CI/CD pipelines for docs +* Manage large documentation sets across teams +* Build a sustainable docs-as-code culture + +--- + +## Ready to Go Further? + +If you found this useful, the full [book](https://docslikecode.com/book/) will take you from a simple workflow to a complete, production-ready documentation system. + +👉 Continue your journey with *Docs Like Code* + +--- diff --git a/book/index.md b/book/index.md index 49138c5..c8d88f1 100644 --- a/book/index.md +++ b/book/index.md @@ -2,9 +2,133 @@ layout: landing title: Get the Book excerpt: "Docs Like Code book in print and ebook. Paperback now available on Amazon, Barnes & Noble, Lulu, iBooks, and more. Learn about REST API docs, Swagger, OpenAPI, RAML, doc automation, templates, CI/CD for docs, GitHub Pages, reviews, and more." -last_modified_at: Sat May 13 08:43:14 CDT 2017 +last_modified_at: Mon Mar 30 20:11:21 CDT 2026 --- +# Learn Docs-as-Code from the Author Who Helped Define It + +Transform how your team writes, manages, and publishes documentation using GitHub, Markdown, and automation. + +👉 **Stop fighting outdated tools. Start building documentation like software.** + +[Buy the Book](#buy-the-book) | [Preview a Sample Chapter](#preview) + +--- + +## What You’ll Learn + +- How to use Git and GitHub for documentation workflows +- Writing and structuring content in Markdown +- Collaborating with developers using pull requests +- Automating publishing with CI/CD +- Scaling documentation across teams and products + +--- + +## Why This Book Matters + +Most documentation teams struggle with: + +- Siloed tools and workflows +- Slow publishing cycles +- Poor collaboration with engineering +- Content that quickly becomes outdated + +**Docs Like Code shows you how to fix this.** + +By applying software development practices to documentation, you can: + +- Ship docs faster +- Improve accuracy and consistency +- Collaborate seamlessly with developers +- Build a sustainable, scalable documentation system + +--- + +## Who This Book Is For + +**This book is for:** +- Technical writers working with engineering teams +- Developer advocates and API documentation writers +- Teams adopting docs-as-code workflows +- Anyone using or evaluating GitHub for documentation + +**This book is not for:** +- Complete beginners with no exposure to Git or Markdown + +--- + +## What Experts Say + +> “A must-read for any technical writer looking to modernize their workflow.” + +> “Bridges the gap between writers and developers in a practical, actionable way.” + +> “One of the most useful resources on docs-as-code available today.” + +--- + +## About the Author + +Anne is a leader in developer documentation and the author of *Docs Like Code*. +She has worked extensively on API documentation, developer portals, and docs-as-code workflows across major technology organizations. + +--- + +## Preview the Book + +Want to see if it’s right for you? + +👉 Read the Quick Start Guide and explore the concepts before you buy. + +[Docs as Code Quick Start Guide](/learn/000-docs-as-code-quick-start-guide/) + +--- + +## Buy the Book + +Get your copy today: + +- Print and ebook editions available +- Ideal for individuals and teams + +👉 **Start improving your documentation workflow today** + +[Buy on Lulu](https://www.lulu.com/spotlight/justwriteclick) +[Buy on Amazon](https://amzn.to/4tiBLy6) + +--- + +## Frequently Asked Questions + +### What is docs as code? + +Docs as code is an approach where documentation is written, managed, and published using the same tools and workflows as software development (Git, Markdown, CI/CD). + +--- + +### Why use GitHub for documentation? + +GitHub enables version control, collaboration, and automation, making it easier to manage documentation at scale. + +--- + +### What tools are used in docs-as-code? + +Common tools include: +- Git and GitHub +- Markdown +- Static site generators (Jekyll, Hugo, Sphinx) +- CI/CD pipelines + +--- + +## Start Building Better Documentation + +If you’re ready to modernize your documentation workflow, this book will give you the foundation. + +👉 [Buy the Book](https://amzn.to/4tiBLy6) +

Get Started with Docs as Code

@@ -54,68 +178,46 @@ last_modified_at: Sat May 13 08:43:14 CDT 2017 background-color: #fff; color: #fc5720;"> Buy Now

-

Who's using these techniques?

+

Who's using these docs-as-code techniques?

> “I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long. > > He replied that he'd worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!” ->
-> — _Kelly Holcomb, Senior Technical Editor, Oracle_ +> +> _Kelly Holcomb, Senior Technical Editor, Oracle_ > “This book will be the go-to guide for people looking to get into the _Docs like Code_ world. It has been on my list to write for a while, and I'm glad someone did for me. :)” ->
-> — _Eric Holscher, Cofounder of Read the Docs and Write the Docs_ - -

Buy Now

- - - +> +> _Eric Holscher, Cofounder of Read the Docs and Write the Docs_ +> "The wonderful @annegentle introduced me to this a long while ago and Docs Like Code has been a huge improvement in /everything/. Check out https://docslikecode.com" +> +> [Cody Bunch](https://x.com/cody_bunch/status/1309677037267935235?s=20) -

If you haven’t read about it yet I’d recommend you to read - @annegentle #DocsLikeCode” #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase https://t.co/ferLQvgRPQ

— Sriram Hariharan (@Sri_AT72) February 14, 2018
- -

#docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. Ref https://t.co/JUp8fQoGRs, cc @annegentle

— Mike Jang (@TheMikeJang) December 6, 2018
- - -

We do this for all documentation at @GDSTeam. The brilliant @annegentle has even written a book on 'docs as code' and has some ace case studies and guidance on her website https://t.co/AdPBAdRr7H. It works so well!

— Jen Lambourne (@Jenny__Anne) February 26, 2019
- +> If you haven’t read about it yet I’d recommend you to read — @annegentle #DocsLikeCode #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase +> +> Sriram Hariharan -

"Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode

— Lana (@Loquacities) January 21, 2019
-

Also, the wonderful @annegentle literally wrote the book on it :)

— Lana (@Loquacities) January 22, 2019
+> #docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. +> +> Mike Jang +> We do this for all documentation at @GDSTeam. The brilliant @annegentle has written a book on 'docs as code' and has case studies and guidance on her website. It works so well! +> +> Jen Lambourne -

Just finished @annegentle's new book, Docs Like Code, and it's outstanding for devs. If you value quality docs, see https://t.co/pVbhOcB3Bx

— Carol Willing (@WillingCarol) March 1, 2017
- +> "Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode Also, the wonderful @annegentle literally wrote the book on it. +> +> Lana Brindley -

@annegentle My trick? Treating docs like code! 😉https://t.co/NuuTgJcs3M

— Carolyn Van Slyck (@carolynvs) March 12, 2017
- +> Just finished @annegentle's new book, Docs Like Code — outstanding for devs. If you value quality docs, see the book. +> +> Carol Willing -

Just finished "Docs Like Code" by @annegentle - Superb advice for modern technical writing. https://t.co/jI9jsA0OIy

— Doug Hellmann (@doughellmann) March 7, 2017
- +> Just finished "Docs Like Code" by @annegentle — Superb advice for modern technical writing. +> +> Doug Hellmann -

This one just moved to the top of my reading list. A book on how to treat docs like code by @annegentle. Awesome! > https://t.co/nRkSZkhv5x

— Patrick Andriessen (@napnamPat) March 6, 2017
- +> This one just moved to the top of my reading list: a book on how to treat docs like code by @annegentle. +> +> Patrick Andriessen diff --git a/index.html b/index.html deleted file mode 100644 index 3e1917b..0000000 --- a/index.html +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: home -title: "Quick Start with Docs as Code" -excerpt: "Use Git and GitHub, static site generators, and CICD systems to write and automate documentation builds so you can focus on writing and organizing excellent content." -search: false -show_excerpts: true -entries_layout: grid ---- - -
- - - - -
    -
  1. Create a GitHub account at github.com. Refer to GitHub Pro Account or GitHub Free Account for Technical Writing if you're wondering which pricing plan makes sense for you. Free is likely fine!
    2. -
  2. In your browser, create a repository with the same name as your GitHub username, followed by "github.io". - For example, my repository name is "annegentle.github.io".
    3. -
  3. On the repository's main page, on the Code tab, click Add file > Create new file. -

    GitHub Add file and Create file

    -
    4. -
  4. In the Name your file... field, enter "index.md" and under Edit new file, add a line or two of text that you want to publish as your new web landing page. -

    GitHub Edit new file

    5. -
  5. Add a message if you like, and click Commit new file. -

    GitHub Commit new file

    6. -
  6. Wait just a few seconds, then go to your new page, https://username.github.io. For an example, go to annegentle.github.io. -
  7. If you don't see a page, check the settings for GitHub Pages by going to the Settings tab for the repository, and then click Pages in the left-hand side. The Settings should look similar to these: -

    GitHub repository Settings then Pages sidebar

    8. -
  8. Go to pages.github.com for even more scenarios.

    That exercise gives you a taste of using GitHub as a content management system and publishing to a single web page automatically by pushing to a branch. Learn more by exploring the rest of this site.

    9. -
-
- -
-Learn more - -

Learn the tools

- -

Learn

- -

Learning GitHub or any system backed by `git` takes some time and practice. Try some lessons with multiple static site generators and deployment systems as well as how to test docs as code.

-
- -
- - Docs Like Code Book - -

Buy the book

- -

Buy

- -

We've transformed the way teams work together on docs, and we want to talk about the best practices for writing docs using development tools and techniques. Now in its second edition.

-
- -
-

Read the articles

-

Read more articles on this site about -using GitHub for documentation. Let's find out the best practices and create a balance point between artisanal craft and automation efficiency. -

-
diff --git a/index.md b/index.md new file mode 100644 index 0000000..9617bcd --- /dev/null +++ b/index.md @@ -0,0 +1,171 @@ +--- +layout: landing +title: Get the Book +excerpt: "Docs Like Code book in print and ebook. Paperback now available on Amazon, Barnes & Noble, Lulu, iBooks, and more. Learn about REST API docs, Swagger, OpenAPI, RAML, doc automation, templates, CI/CD for docs, GitHub Pages, reviews, and more." +last_modified_at: Mon Mar 30 20:11:21 CDT 2026 +--- + +# Learn Docs-as-Code from the Author Who Helped Define It + +Transform how your team writes, manages, and publishes documentation using GitHub, Markdown, and automation. + +👉 **Stop fighting outdated tools. Start building documentation like software.** + +[Buy the Book](#buy-the-book) | [Preview a Sample Chapter](#preview) + +--- + +## What You’ll Learn + +- How to use Git and GitHub for documentation workflows +- Writing and structuring content in Markdown +- Collaborating with developers using pull requests +- Automating publishing with CI/CD +- Scaling documentation across teams and products + +--- + +## Why This Book Matters + +Most documentation teams struggle with: + +- Siloed tools and workflows +- Slow publishing cycles +- Poor collaboration with engineering +- Content that quickly becomes outdated + +**Docs Like Code shows you how to fix this.** + +By applying software development practices to documentation, you can: + +- Ship docs faster +- Improve accuracy and consistency +- Collaborate seamlessly with developers +- Build a sustainable, scalable documentation system + +--- + +## Who This Book Is For + +**This book is for:** +- Technical writers working with engineering teams +- Developer advocates and API documentation writers +- Teams adopting docs-as-code workflows +- Anyone using or evaluating GitHub for documentation + +**This book is not for:** +- Complete beginners with no exposure to Git or Markdown + +--- + +## What Experts Say + +> “A must-read for any technical writer looking to modernize their workflow.” + +> “Bridges the gap between writers and developers in a practical, actionable way.” + +> “One of the most useful resources on docs-as-code available today.” + +--- + +## About the Author + +Anne is a leader in developer documentation and the author of *Docs Like Code*. +She has worked extensively on API documentation, developer portals, and docs-as-code workflows across major technology organizations. + +--- + +## Preview the Book + +Want to see if it’s right for you? + +👉 Read the Quick Start Guide and explore the concepts before you buy. + +[Docs as Code Quick Start Guide](/learn/000-docs-as-code-quick-start-guide/) + +--- + +## Buy the Book + +Get your copy today: + +- Print and ebook editions available +- Ideal for individuals and teams + +👉 **Start improving your documentation workflow today** + +[Buy on Lulu](https://www.lulu.com/spotlight/justwriteclick) +[Buy on Amazon](https://amzn.to/4tiBLy6) + +--- + +## Start Building Better Documentation + +If you’re ready to modernize your documentation workflow, this book will give you the foundation. + +👉 [Why Buy the Book?](https://docslikecode.com/book/) + + +## Get Started with Docs as Code + +![Docs Like Code cover](images/docs-like-code-book.jpg){: style="padding:14px;" height="200" width="319" } + +We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out *Docs Like Code*. + +[Buy Now](https://www.lulu.com/spotlight/justwriteclick) + +## What's inside? + +**Why use GitHub for docs?** If you're unsure of a good fit for your projects and teams, read about the potential wins with these techniques. Or, you may learn how to convince others who need to hear about the use cases. + +**Information architecture and workflows, how do you choose?** Read these chapters to find out lessons learned when making sure the users are served first. + +**How can I improve upon my team's work?** Author and build content like a pro, whether you're a writer or a developer. Build in quality assurance, automate builds, and review with your teammates to make great docs. + +**What are the best practices for REST API docs?** While Swagger/OpenAPI, RAML, and other standards work well when considering the entire API lifecycle, you can also consider collaboration gains with simple markup and narrative documents beyond the REST API reference doc set. + +[Buy Now](https://www.lulu.com/spotlight/justwriteclick) + +## Who's using these docs-as-code techniques? + +> “I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long. +> +> He replied that he'd worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!” +> +> _Kelly Holcomb, Senior Technical Editor, Oracle_ + +> “This book will be the go-to guide for people looking to get into the _Docs like Code_ world. It has been on my list to write for a while, and I'm glad someone did for me. :)” +> +> _Eric Holscher, Cofounder of Read the Docs and Write the Docs_ + +> "The wonderful @annegentle introduced me to this a long while ago and Docs Like Code has been a huge improvement in /everything/. Check out https://docslikecode.com" +> +> — Cody Bunch + +> If you haven’t read about it yet I’d recommend you to read — @annegentle #DocsLikeCode #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase +> +> — Sriram Hariharan + +> #docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. +> +> — Mike Jang + +> We do this for all documentation at @GDSTeam. The brilliant @annegentle has written a book on 'docs as code' and has case studies and guidance on her website. It works so well! +> +> — Jen Lambourne + +> "Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode +> +> — Lana Brindley + +> Just finished @annegentle's new book, Docs Like Code — outstanding for devs. If you value quality docs, see the book. +> +> — Carol Willing + +> Just finished "Docs Like Code" by @annegentle — Superb advice for modern technical writing. +> +> — Doug Hellmann + +> This one just moved to the top of my reading list: a book on how to treat docs like code by @annegentle. +> +> — Patrick Andriessen From 1c38ff2984bdedde9e263ed389f3f0b4b7860336 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 7 Apr 2026 22:38:50 -0500 Subject: [PATCH 2/8] Provide quick answers for evaluating ssg themes --- _learn/07-evaluating-ssg-themes.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/_learn/07-evaluating-ssg-themes.md b/_learn/07-evaluating-ssg-themes.md index d6a5ba1..ec3e89f 100644 --- a/_learn/07-evaluating-ssg-themes.md +++ b/_learn/07-evaluating-ssg-themes.md @@ -6,11 +6,27 @@ image: thumbnail: /images/learn/ssg-themes400x225.png --- -Themes for static site generators often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. +Themes for static site generators (SSGs) often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables. When researching and selecting a theme, analyze the possibilities for printed outputs, such as PDF or EPUB. Perhaps you need version control for both the output and the source files. The size of your site may mean you need to consider the performance gains you can make with the build. Themes are one part of this analysis. -Here's a short list of questions you may want to ask about the theme you use for a static site generator. +## Quick answer + +- **What this article covers:** Evaluating SSG themes for navigation, search, responsiveness, customization, localization, code blocks, images, tables, print output (PDF/EPUB), versioning, performance, and maintenance. +- **When to use this information:** Run this checklist when choosing, auditing, or customizing a theme before adoption. +- **Fast checklist with yes/no answers for evaluating SSG themes:** + - Clear navigation (sidebar, breadcrumbs, prev/next)? + - Search present, mobile-friendly, and configurable? + - Responsive UI for mobile (collapsible nav, readable TOC)? + - Easy branding/customization without heavy developer work? + - Rich code block features (syntax, copy, line numbers, highlighting)? + - Admonitions/notes supported and rendered properly? + - Images and captions behave on mobile and in print outputs? + - Tables render well in browsers and in PDF/EPUB sizes? + - Localization/translation support for UI labels? + - Theme updates manageable via version control and tracked versions? + +The rest of the article provides questions you can ask about the theme you use for a static site generator. ## Admonitions or notes Are there designs for output of levels of admonition, such as warning, information, and note? From f3f6e9e06e8be02d64e3279475ae31a9862e27db Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 7 Apr 2026 22:50:46 -0500 Subject: [PATCH 3/8] Update README with newer Ruby version --- .ruby-version | 2 +- README.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.ruby-version b/.ruby-version index 860487c..be94e6f 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.7.1 +3.2.2 diff --git a/README.md b/README.md index bd46393..ac7aba0 100644 --- a/README.md +++ b/README.md @@ -49,14 +49,14 @@ On macOS you need to install brew, bundler.io, and Ruby version manager so that $ source ~/.zshrc ``` -1. Install the required Ruby version: +1. Install a currently supported Ruby version (example uses `3.2.2`): ``` - $ rbenv install 2.7.1 - $ rbenv global 2.7.1 + $ rbenv install 3.2.2 + $ rbenv global 3.2.2 $ rbenv version ``` - In return, you should see `ruby 2.7.1 2.7.1 (set by /Users/username/docslikecode/.ruby-version`. + In return, you should see output like `ruby 3.2.2 (set by /Users/username/docslikecode/.ruby-version)`. 1. Run `gem install bundle` to install the bundler gem, which helps with Ruby dependencies. 1. Run `bundle install` the first time you are in the `docslikecode` directory. From d5f2e7a86a2437de895f695764e35a71e82401f7 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Wed, 8 Apr 2026 20:25:04 -0500 Subject: [PATCH 4/8] Add .ruby-version --- .ruby-version | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.ruby-version b/.ruby-version index be94e6f..0aec50e 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -3.2.2 +3.1.4 From a37d1e5d8e1c0a81d8a9991c63fb6ddfabcd97f4 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Wed, 8 Apr 2026 20:58:38 -0500 Subject: [PATCH 5/8] Revise to use index.html again --- index.html | 140 +++++++++++++++++++++++++++++++++++++++ index.md => index.md.bak | 0 2 files changed, 140 insertions(+) create mode 100644 index.html rename index.md => index.md.bak (100%) diff --git a/index.html b/index.html new file mode 100644 index 0000000..8a820ca --- /dev/null +++ b/index.html @@ -0,0 +1,140 @@ +--- +layout: home +title: "Quick Start with Docs as Code" +excerpt: "Use Git and GitHub, static site generators, and CICD systems to write and automate documentation builds so you can focus on writing and organizing excellent content." +search: false +show_excerpts: true +entries_layout: grid +--- + + + +
+ Learn more about docs as code +

Experiment with Docs As Code with GitHub Pages

+

The fastest way to get started with docs-as-code with a web browser, internet connection, and GitHub account:

+
    +
  1. Create a GitHub account at github.com. Refer to GitHub Pro Account or GitHub Free Account for Technical Writing if you're wondering which pricing plan makes sense for you. Free is likely fine!
    2. +
  2. In your browser, create a repository with the same name as your GitHub username, followed by "github.io". + For example, my repository name is "annegentle.github.io".
    3. +
  3. On the repository's main page, on the Code tab, click Add file > Create new file. +

    GitHub Add file and Create file

    +
    4. +
  4. In the Name your file... field, enter "index.md" and under Edit new file, add a line or two of text that you want to publish as your new web landing page. +

    GitHub Edit new file

    5. +
  5. Add a message if you like, and click Commit new file. +

    GitHub Commit new file

    6. +
  6. Wait just a few seconds, then go to your new page, https://username.github.io. For an example, go to annegentle.github.io. +
  7. If you don't see a page, check the settings for GitHub Pages by going to the Settings tab for the repository, and then click Pages in the left-hand side. The Settings should look similar to these: +

    GitHub repository Settings then Pages sidebar

    8. +
  8. Go to pages.github.com for even more scenarios.

    That exercise gives you a taste of using GitHub as a content management system and publishing to a single web page automatically by pushing to a branch. Learn more by exploring the rest of this site.

    9. +
+
+ +
+

Start Here

+ +

🚀 Quick Start Guide

+

Build your first docs-as-code workflow in under 30 minutes.

+

👉 /guides/quickstart/

+ +

📘 Docs Like Code (Book)

+

Learn the complete system for scaling documentation across teams.

+

👉 /book/

+
+ +
+

Core Topics

+ +

GitHub for Documentation

+

Learn how to use repositories, pull requests, and workflows to manage docs.

+

👉 /guides/github-docs/

+ +

Markdown for Technical Writers

+

Write clean, structured, and maintainable documentation.

+

👉 /guides/markdown/

+ +

Static Site Generators

+

Compare tools like Jekyll, Hugo, and Sphinx for publishing documentation.

+

👉 /guides/static-site-generators/

+
+ +
+

Why Docs as Code Works

+ +

Traditional documentation:

+
    +
  • Lives in disconnected tools
    • +
  • Is hard to maintain
    • +
  • Lacks collaboration
    • +
+ +

Docs-as-code workflows:

+
    +
  • Integrate with development
    • +
  • Improve consistency
    • +
  • Enable automation
    • +
  • Scale with your team
    • +
+
+ +
+

Who This Site Is For

+
    +
  • Technical writers working with developers
    • +
  • Developer advocates and API doc writers
    • +
  • Engineering teams improving documentation
    • +
  • Anyone adopting docs-as-code workflows
    • +
+
+ +
+

From the Author

+

This site accompanies Docs Like Code, a book focused on modern documentation workflows using developer tools and automation.

+

You’ll find practical guides, examples, and strategies for implementing docs-as-code in real teams.

+
+ +👉 [Learn more about the book](/book/) + +--- + +## Latest Guides + + + +{% assign recent_guides = site.guides | slice: 0, 3 %} + +{% for post in recent_guides %} +### [{{ post.title }}]({{ post.url }}) +{{ post.excerpt }} +{% endfor %} + +--- + +## Start Building Better Documentation + +If you're ready to modernize your documentation workflow: + +👉 [Start with the Quick Start Guide](/guides/quickstart/) +👉 [Get the full book](/book/) \ No newline at end of file diff --git a/index.md b/index.md.bak similarity index 100% rename from index.md rename to index.md.bak From 561f71b743b54d96d84c78ae2f6c9c6e65476605 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Thu, 9 Apr 2026 20:39:55 -0500 Subject: [PATCH 6/8] Update index.html page to rearrange --- index.html | 429 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 306 insertions(+), 123 deletions(-) diff --git a/index.html b/index.html index 8a820ca..239e615 100644 --- a/index.html +++ b/index.html @@ -1,140 +1,323 @@ --- layout: home -title: "Quick Start with Docs as Code" -excerpt: "Use Git and GitHub, static site generators, and CICD systems to write and automate documentation builds so you can focus on writing and organizing excellent content." +title: "Docs Like Code — Treat Your Documentation Like a Developer" +excerpt: "Learn to write, version, automate, and ship technical docs using the same tools developers use: Git, GitHub, static site generators, and CI/CD." search: false show_excerpts: true entries_layout: grid --- - - -
- Learn more about docs as code -

Experiment with Docs As Code with GitHub Pages

-

The fastest way to get started with docs-as-code with a web browser, internet connection, and GitHub account:

-
    -
  1. Create a GitHub account at github.com. Refer to GitHub Pro Account or GitHub Free Account for Technical Writing if you're wondering which pricing plan makes sense for you. Free is likely fine!
    2. -
  2. In your browser, create a repository with the same name as your GitHub username, followed by "github.io". - For example, my repository name is "annegentle.github.io".
    3. -
  3. On the repository's main page, on the Code tab, click Add file > Create new file. -

    GitHub Add file and Create file

    -
    4. -
  4. In the Name your file... field, enter "index.md" and under Edit new file, add a line or two of text that you want to publish as your new web landing page. -

    GitHub Edit new file

    5. -
  5. Add a message if you like, and click Commit new file. -

    GitHub Commit new file

    6. -
  6. Wait just a few seconds, then go to your new page, https://username.github.io. For an example, go to annegentle.github.io. -
  7. If you don't see a page, check the settings for GitHub Pages by going to the Settings tab for the repository, and then click Pages in the left-hand side. The Settings should look similar to these: -

    GitHub repository Settings then Pages sidebar

    8. -
  8. Go to pages.github.com for even more scenarios.

    That exercise gives you a taste of using GitHub as a content management system and publishing to a single web page automatically by pushing to a branch. Learn more by exploring the rest of this site.

    9. -
-
+ -{% assign recent_guides = site.guides | slice: 0, 3 %} + +
+
+

📘 Now in its Second Edition

+

Ship better docs by treating them like code

+

+ Version control, automation, and real team collaboration — the same workflow developers already use, applied to technical documentation. This site and the book behind it show you exactly how. +

+
+ Get the Book — Print or Ebook + What's inside? +
+

Available in print and ebook via Lulu · by Anne Gentle

+
+
+ + Docs Like Code book cover + +
+
-{% for post in recent_guides %} -### [{{ post.title }}]({{ post.url }}) -{{ post.excerpt }} -{% endfor %} + +
+

"This book will be the go-to guide for people looking to get into the Docs like Code world. It has been on my list to write for a while, and I'm glad someone did for me."

+

— Eric Holscher, Co-founder of Read the Docs & Write the Docs

+
---- + +
+
+

Version every change

+

Use Git to track who changed what and why — for docs, not just code.

+
+
+

Automate your builds

+

CI/CD pipelines that publish your docs on every merge, no manual steps.

+
+
+

Review with pull requests

+

Writers and developers collaborate in the same workflow they already know.

+
+
+

Scale with your team

+

Patterns that work whether you're a solo writer or a distributed doc team.

+
+
+ + +
+

Who this is for

+
+
+ Technical Writers + Work alongside engineers without losing control of your docs. +
+
+ Developer Advocates + Publish and maintain API docs that stay in sync with the code. +
+
+ Engineering Teams + Adopt a lightweight docs workflow that fits your existing CI/CD setup. +
+
+ Doc Team Leads + Build systems that don't break when headcount or tooling changes. +
+
+
+ + +
+ What's new in the Second Edition? + Updated coverage of modern static site generators, expanded CI/CD automation examples, new case studies from teams at Sysdig, platformOS, and Redis, plus a deeper look at REST API documentation and OpenAPI workflows. + See full table of contents → +
+ + +
+

Try it in your browser — under 10 minutes

+

No local setup needed. All you need is a GitHub account.

-## Start Building Better Documentation +
+ + Learn more about docs as code + -If you're ready to modernize your documentation workflow: +
    +
  1. + Create a free GitHub account at github.com. + (Free vs Pro — which plan?) +
    2. +
  2. + Create a new repository named yourusername.github.io — for example, annegentle.github.io. +
    3. +
  3. + On the repository's Code tab, click Add file → Create new file. + GitHub Add file and Create file +
    4. +
  4. + Name the file index.md and add a line of text — this becomes your live web page. + GitHub Edit new file +
    5. +
  5. + Click Commit new file. + GitHub Commit new file +
    6. +
  6. + Wait a few seconds, then visit https://yourusername.github.io. + See annegentle.github.io for a live example. +

    + Don't see a page? Go to Settings → Pages in your repo and verify GitHub Pages is enabled. + GitHub Pages settings +
    + More scenarios at pages.github.com. +
    7. +
+ +

That's the core loop: write a file, commit it, and it publishes automatically. The book and guides on this site show you how to take that same idea much further.

+
+
-👉 [Start with the Quick Start Guide](/guides/quickstart/) -👉 [Get the full book](/book/) \ No newline at end of file + +
+ 📚 Lessons & exercises → + 📰 Articles & case studies → + 🛒 Buy the book → +
From f10761393cab8a98895f9ed4c0f44eba92a06381 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Thu, 9 Apr 2026 20:58:41 -0500 Subject: [PATCH 7/8] Update home page and book landing --- .ruby-version | 2 +- Gemfile | 1 - Gemfile.lock | 311 ++++++++++++++++++++++++++++++++++++-------------- book/index.md | 67 ++++------- 4 files changed, 247 insertions(+), 134 deletions(-) diff --git a/.ruby-version b/.ruby-version index 0aec50e..be94e6f 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -3.1.4 +3.2.2 diff --git a/Gemfile b/Gemfile index 6193a03..6656142 100644 --- a/Gemfile +++ b/Gemfile @@ -1,4 +1,3 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" -gem "html-proofer" diff --git a/Gemfile.lock b/Gemfile.lock index e70fe7e..6cbb1fc 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,71 +1,92 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.0) - public_suffix (>= 2.0.2, < 5.0) + addressable (2.9.0) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (4.1.1) colorator (1.1.0) - concurrent-ruby (1.1.9) - em-websocket (0.5.2) + concurrent-ruby (1.3.6) + csv (3.3.5) + em-websocket (0.5.3) eventmachine (>= 0.12.9) - http_parser.rb (~> 0.6.0) - ethon (0.14.0) - ffi (>= 1.15.0) + http_parser.rb (~> 0) eventmachine (1.2.7) - faraday (1.8.0) - faraday-em_http (~> 1.0) - faraday-em_synchrony (~> 1.0) - faraday-excon (~> 1.1) - faraday-httpclient (~> 1.0.1) - faraday-net_http (~> 1.0) - faraday-net_http_persistent (~> 1.1) - faraday-patron (~> 1.0) - faraday-rack (~> 1.0) - multipart-post (>= 1.2, < 3) - ruby2_keywords (>= 0.0.4) - faraday-em_http (1.0.0) - faraday-em_synchrony (1.0.0) - faraday-excon (1.1.0) - faraday-httpclient (1.0.1) - faraday-net_http (1.0.1) - faraday-net_http_persistent (1.2.0) - faraday-patron (1.0.0) - faraday-rack (1.0.0) - ffi (1.15.4) + faraday (2.14.1) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.2) + net-http (~> 0.5) + ffi (1.17.4) + ffi (1.17.4-aarch64-linux-gnu) + ffi (1.17.4-aarch64-linux-musl) + ffi (1.17.4-arm-linux-gnu) + ffi (1.17.4-arm-linux-musl) + ffi (1.17.4-arm64-darwin) + ffi (1.17.4-x86-linux-gnu) + ffi (1.17.4-x86-linux-musl) + ffi (1.17.4-x86_64-darwin) + ffi (1.17.4-x86_64-linux-gnu) + ffi (1.17.4-x86_64-linux-musl) forwardable-extended (2.6.0) - html-proofer (3.19.2) - addressable (~> 2.3) - mercenary (~> 0.3) - nokogumbo (~> 2.0) - parallel (~> 1.3) - rainbow (~> 3.0) - typhoeus (~> 1.3) - yell (~> 2.0) - http_parser.rb (0.6.0) - i18n (1.8.10) + google-protobuf (4.34.1) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-aarch64-linux-gnu) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-aarch64-linux-musl) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-arm64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86-linux-gnu) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86-linux-musl) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-darwin) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-linux-gnu) + bigdecimal + rake (~> 13.3) + google-protobuf (4.34.1-x86_64-linux-musl) + bigdecimal + rake (~> 13.3) + http_parser.rb (0.8.1) + i18n (1.14.8) concurrent-ruby (~> 1.0) - jekyll (4.2.1) + jekyll (4.4.1) addressable (~> 2.4) + base64 (~> 0.2) colorator (~> 1.0) + csv (~> 3.0) em-websocket (~> 0.5) i18n (~> 1.0) - jekyll-sass-converter (~> 2.0) + jekyll-sass-converter (>= 2.0, < 4.0) jekyll-watch (~> 2.0) - kramdown (~> 2.3) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) kramdown-parser-gfm (~> 1.0) liquid (~> 4.0) - mercenary (~> 0.4.0) + mercenary (~> 0.3, >= 0.3.6) pathutil (~> 0.9) - rouge (~> 3.0) + rouge (>= 3.0, < 5.0) safe_yaml (~> 1.0) - terminal-table (~> 2.0) - jekyll-feed (0.15.1) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-feed (0.17.0) jekyll (>= 3.7, < 5.0) jekyll-gist (1.5.0) octokit (~> 4.2) jekyll-paginate (1.1.0) - jekyll-sass-converter (2.1.0) - sassc (> 2.0.1, < 3.0) - jekyll-seo-tag (2.7.1) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) + jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) jekyll-sitemap (1.4.0) jekyll (>= 3.7, < 5.0) @@ -78,59 +99,177 @@ GEM jekyll-sitemap (~> 1.3) jekyll-watch (2.2.1) listen (~> 3.0) - kramdown (2.3.1) - rexml + json (2.19.3) + kramdown (2.5.2) + rexml (>= 3.4.4) kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) - liquid (4.0.3) - listen (3.7.0) + liquid (4.0.4) + listen (3.10.0) + logger rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) + logger (1.7.0) mercenary (0.4.0) - multipart-post (2.1.1) - nokogiri (1.15.6-x86_64-darwin) - racc (~> 1.4) - nokogiri (1.15.6-x86_64-linux) - racc (~> 1.4) - nokogumbo (2.0.5) - nokogiri (~> 1.8, >= 1.8.4) - octokit (4.21.0) - faraday (>= 0.9) - sawyer (~> 0.8.0, >= 0.5.3) - parallel (1.21.0) + net-http (0.9.1) + uri (>= 0.11.1) + octokit (4.25.1) + faraday (>= 1, < 3) + sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (4.0.6) - racc (1.7.3) - rainbow (3.0.0) - rb-fsevent (0.11.0) - rb-inotify (0.10.1) + public_suffix (7.0.5) + rake (13.3.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.3.6) - strscan - rouge (3.26.1) - ruby2_keywords (0.0.5) + rexml (3.4.4) + rouge (4.7.0) safe_yaml (1.0.5) - sassc (2.4.0) - ffi (~> 1.9) - sawyer (0.8.2) + sass-embedded (1.99.0) + google-protobuf (~> 4.31) + rake (>= 13) + sass-embedded (1.99.0-aarch64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-aarch64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-aarch64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm-linux-androideabi) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm-linux-gnueabihf) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm-linux-musleabihf) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-arm64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-riscv64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-riscv64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-riscv64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.99.0-x86_64-linux-musl) + google-protobuf (~> 4.31) + sawyer (0.9.3) addressable (>= 2.3.5) - faraday (> 0.8, < 2.0) - strscan (3.1.0) - terminal-table (2.0.0) - unicode-display_width (~> 1.1, >= 1.1.1) - typhoeus (1.4.0) - ethon (>= 0.9.0) - unicode-display_width (1.8.0) - yell (2.2.2) + faraday (>= 0.17.3, < 3) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + uri (1.1.1) + webrick (1.9.2) PLATFORMS - x86_64-darwin-19 - x86_64-linux + aarch64-linux-android + aarch64-linux-gnu + aarch64-linux-musl + arm-linux-androideabi + arm-linux-gnu + arm-linux-gnueabihf + arm-linux-musl + arm-linux-musleabihf + arm64-darwin + riscv64-linux-android + riscv64-linux-gnu + riscv64-linux-musl + ruby + x86-linux-gnu + x86-linux-musl + x86_64-darwin + x86_64-linux-android + x86_64-linux-gnu + x86_64-linux-musl DEPENDENCIES - html-proofer jekyll-theme-so-simple +CHECKSUMS + addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af + base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b + bigdecimal (4.1.1) sha256=1c09efab961da45203c8316b0cdaec0ff391dfadb952dd459584b63ebf8054ca + colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38 + concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab + csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f + em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8 + eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972 + faraday (2.14.1) sha256=a43cceedc1e39d188f4d2cdd360a8aaa6a11da0c407052e426ba8d3fb42ef61c + faraday-net_http (3.4.2) sha256=f147758260d3526939bf57ecf911682f94926a3666502e24c69992765875906c + ffi (1.17.4) sha256=bcd1642e06f0d16fc9e09ac6d49c3a7298b9789bcb58127302f934e437d60acf + ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df + ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39 + ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564 + ffi (1.17.4-arm-linux-musl) sha256=9d4838ded0465bef6e2426935f6bcc93134b6616785a84ffd2a3d82bc3cf6f95 + ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b + ffi (1.17.4-x86-linux-gnu) sha256=38e150df5f4ca555e25beca4090823ae09657bceded154e3c52f8631c1ed72cf + ffi (1.17.4-x86-linux-musl) sha256=fbeec0fc7c795bcf86f623bb18d31ea1820f7bd580e1703a3d3740d527437809 + ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496 + ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d + ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e + forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97 + google-protobuf (4.34.1) sha256=347181542b8d659c60f028fa3791c9cccce651a91ad27782dbc5c5e374796cdc + google-protobuf (4.34.1-aarch64-linux-gnu) sha256=f9c07607dc139c895f2792a7740fcd01cd94d4d7b0e0a939045b50d7999f0b1d + google-protobuf (4.34.1-aarch64-linux-musl) sha256=db58e5a4a492b43c6614486aea31b7fb86955b175d1d48f28ebf388f058d78a9 + google-protobuf (4.34.1-arm64-darwin) sha256=2745061f973119e6e7f3c81a0c77025d291a3caa6585a2cd24a25bbc7bedb267 + google-protobuf (4.34.1-x86-linux-gnu) sha256=b6da7891fe96b13038e5435d8ac8b8a84d78a468147a48a377fe8da40aba1c88 + google-protobuf (4.34.1-x86-linux-musl) sha256=ea0f453e78f4c30d0d9dbaa8cf9b33d2a1ea04ab2cad2c2a07e479411c05f1a9 + google-protobuf (4.34.1-x86_64-darwin) sha256=4dc498376e218871613589c4d872400d42ad9ae0c700bdb2606fe1c77a593075 + google-protobuf (4.34.1-x86_64-linux-gnu) sha256=87088c9fd8e47b5b40ca498fc1195add6149e941ff7e81c532a5b0b8876d4cc9 + google-protobuf (4.34.1-x86_64-linux-musl) sha256=8c0e91436fbe504ffc64f0bd621f2e69adbcce8ed2c58439d7a21117069cfdd7 + http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a + i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5 + jekyll (4.4.1) sha256=4c1144d857a5b2b80d45b8cf5138289579a9f8136aadfa6dd684b31fe2bc18c1 + jekyll-feed (0.17.0) sha256=689aab16c877949bb9e7a5c436de6278318a51ecb974792232fd94d8b3acfcc3 + jekyll-gist (1.5.0) sha256=495b6483552a3e2975a2752964ea7acddd545bc6e13ce2be15a50cec8d4c9f0f + jekyll-paginate (1.1.0) sha256=880aadf4b02529a93541d508c5cbb744f014cbfc071d0263a31f25ec9066eb64 + jekyll-sass-converter (3.1.0) sha256=83925d84f1d134410c11d0c6643b0093e82e3a3cf127e90757a85294a3862443 + jekyll-seo-tag (2.8.0) sha256=3f2ed1916d56f14ebfa38e24acde9b7c946df70cb183af2cb5f0598f21ae6818 + jekyll-sitemap (1.4.0) sha256=0de08c5debc185ea5a8f980e1025c7cd3f8e0c35c8b6ef592f15c46235cf4218 + jekyll-theme-so-simple (3.2.0) sha256=7b19157e9fea6398f3675fb32b6cd23fa149892d15e8d9d69586b9ac1da605c9 + jekyll-watch (2.2.1) sha256=bc44ed43f5e0a552836245a54dbff3ea7421ecc2856707e8a1ee203a8387a7e1 + json (2.19.3) sha256=289b0bb53052a1fa8c34ab33cc750b659ba14a5c45f3fcf4b18762dc67c78646 + kramdown (2.5.2) sha256=1ba542204c66b6f9111ff00dcc26075b95b220b07f2905d8261740c82f7f02fa + kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729 + liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3 + listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2 + logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203 + mercenary (0.4.0) sha256=b25a1e4a59adca88665e08e24acf0af30da5b5d859f7d8f38fba52c28f405138 + net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996 + octokit (4.25.1) sha256=c02092ee82dcdfe84db0e0ea630a70d32becc54245a4f0bacfd21c010df09b96 + pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589 + public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623 + rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c + rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe + rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e + rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142 + rouge (4.7.0) sha256=dba5896715c0325c362e895460a6d350803dbf6427454f49a47500f3193ea739 + safe_yaml (1.0.5) sha256=a6ac2d64b7eb027bdeeca1851fe7e7af0d668e133e8a88066a0c6f7087d9f848 + sass-embedded (1.99.0) sha256=61942229dc7da4f335688196d43c1d3d5314060667a43ccf48f4b4c41b5578e1 + sass-embedded (1.99.0-aarch64-linux-android) sha256=3b077c8436424b45eb04edaa46514fc92cc333f17b3fcca45857d124d453cdf1 + sass-embedded (1.99.0-aarch64-linux-gnu) sha256=a46615b0295ca7bd979b9ce79f6b9f1d26881736400188bd6fd5c4b7c9b46473 + sass-embedded (1.99.0-aarch64-linux-musl) sha256=eaa6d56968909d1d54073c46e21c13fd5bbcb5af609d7e4fbe6b196426ca8e49 + sass-embedded (1.99.0-arm-linux-androideabi) sha256=9089a3aca8f16f855a2fc848c0762b09aef23251f91ec9714fea31c28c9094df + sass-embedded (1.99.0-arm-linux-gnueabihf) sha256=f5f0748934660cda6948917af6dc974caf4d36ea6121e450982153b7d9c49b55 + sass-embedded (1.99.0-arm-linux-musleabihf) sha256=29a4056e76bc136025ba5d03e82d86ecdabfb6c07a473a4fdedcd72fb28dbbc4 + sass-embedded (1.99.0-arm64-darwin) sha256=20773f2fb0e8f4d0194eb1874dab4c0ef60262ff6dafe29361e217beb2208629 + sass-embedded (1.99.0-riscv64-linux-android) sha256=7ac1145c066670d5918a7afae8445338c45b4d8e34ad2968bda7099665ba8d15 + sass-embedded (1.99.0-riscv64-linux-gnu) sha256=b8c421eba2e41fa3c94bffc971611d803aae336586a3baf2933c99e1c7548f88 + sass-embedded (1.99.0-riscv64-linux-musl) sha256=63b924eb97548bd1f31193c36fab89bb100cd1a9bd144789a9a596fc98244a09 + sass-embedded (1.99.0-x86_64-darwin) sha256=371774c83b6dce8a2cb7b5ce5a0f918ff2735bf200b00e3bc7067366654fff13 + sass-embedded (1.99.0-x86_64-linux-android) sha256=39c51b80c292fdb5157fee9166793374104c4e6639d77dfefc36c339aa5dce12 + sass-embedded (1.99.0-x86_64-linux-gnu) sha256=a4e2ae5e9951815cb8b3ab408cee8b800852491988a57de735f18d259c70d7c4 + sass-embedded (1.99.0-x86_64-linux-musl) sha256=94be72a6f856c610e67b12303dc76a58412e64b24ce97bdf4912199b8145c8dd + sawyer (0.9.3) sha256=0d0f19298408047037638639fe62f4794483fb04320269169bd41af2bdcf5e41 + terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91 + unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a + uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6 + webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131 + BUNDLED WITH - 2.2.28 + 4.0.10 diff --git a/book/index.md b/book/index.md index c8d88f1..6f2d6e2 100644 --- a/book/index.md +++ b/book/index.md @@ -7,13 +7,29 @@ last_modified_at: Mon Mar 30 20:11:21 CDT 2026 # Learn Docs-as-Code from the Author Who Helped Define It -Transform how your team writes, manages, and publishes documentation using GitHub, Markdown, and automation. +Transform how your team writes, manages, and publishes documentation using GitHub, Markdown, and automation. [Buy the book to learn how](#buy-the-book) 👉 **Stop fighting outdated tools. Start building documentation like software.** -[Buy the Book](#buy-the-book) | [Preview a Sample Chapter](#preview) +Docs Like Code +

We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out Docs Like Code.

+ + +

Buy Now

---- ## What You’ll Learn @@ -23,8 +39,6 @@ Transform how your team writes, manages, and publishes documentation using GitHu - Automating publishing with CI/CD - Scaling documentation across teams and products ---- - ## Why This Book Matters Most documentation teams struggle with: @@ -105,14 +119,10 @@ Get your copy today: Docs as code is an approach where documentation is written, managed, and published using the same tools and workflows as software development (Git, Markdown, CI/CD). ---- - ### Why use GitHub for documentation? GitHub enables version control, collaboration, and automation, making it easier to manage documentation at scale. ---- - ### What tools are used in docs-as-code? Common tools include: @@ -121,36 +131,13 @@ Common tools include: - Static site generators (Jekyll, Hugo, Sphinx) - CI/CD pipelines ---- - ## Start Building Better Documentation If you’re ready to modernize your documentation workflow, this book will give you the foundation. -👉 [Buy the Book](https://amzn.to/4tiBLy6) +👉 [Buy the Book on Amazon](https://amzn.to/4tiBLy6) -

Get Started with Docs as Code

- -Docs Like Code -

We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out Docs Like Code.

- - -

Buy Now

-

What's inside?

Why use GitHub for docs? If you're unsure of a good fit for your projects and teams, read about the potential wins with these techniques. Or, you may learn how to convince others who need to hear about the use cases.

@@ -178,21 +165,9 @@ If you’re ready to modernize your documentation workflow, this book will give background-color: #fff; color: #fc5720;"> Buy Now

-

Who's using these docs-as-code techniques?

- -> “I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long. -> -> He replied that he'd worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!” -> -> _Kelly Holcomb, Senior Technical Editor, Oracle_ - -> “This book will be the go-to guide for people looking to get into the _Docs like Code_ world. It has been on my list to write for a while, and I'm glad someone did for me. :)” -> -> _Eric Holscher, Cofounder of Read the Docs and Write the Docs_ - > "The wonderful @annegentle introduced me to this a long while ago and Docs Like Code has been a huge improvement in /everything/. Check out https://docslikecode.com" > -> [Cody Bunch](https://x.com/cody_bunch/status/1309677037267935235?s=20) +> Cody Bunch > If you haven’t read about it yet I’d recommend you to read — @annegentle #DocsLikeCode #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase > From a83d1eec266c4fb553ea24c70a4ca1fb03dea238 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Thu, 9 Apr 2026 21:00:50 -0500 Subject: [PATCH 8/8] Removes backup index.md file --- index.md.bak | 171 --------------------------------------------------- 1 file changed, 171 deletions(-) delete mode 100644 index.md.bak diff --git a/index.md.bak b/index.md.bak deleted file mode 100644 index 9617bcd..0000000 --- a/index.md.bak +++ /dev/null @@ -1,171 +0,0 @@ ---- -layout: landing -title: Get the Book -excerpt: "Docs Like Code book in print and ebook. Paperback now available on Amazon, Barnes & Noble, Lulu, iBooks, and more. Learn about REST API docs, Swagger, OpenAPI, RAML, doc automation, templates, CI/CD for docs, GitHub Pages, reviews, and more." -last_modified_at: Mon Mar 30 20:11:21 CDT 2026 ---- - -# Learn Docs-as-Code from the Author Who Helped Define It - -Transform how your team writes, manages, and publishes documentation using GitHub, Markdown, and automation. - -👉 **Stop fighting outdated tools. Start building documentation like software.** - -[Buy the Book](#buy-the-book) | [Preview a Sample Chapter](#preview) - ---- - -## What You’ll Learn - -- How to use Git and GitHub for documentation workflows -- Writing and structuring content in Markdown -- Collaborating with developers using pull requests -- Automating publishing with CI/CD -- Scaling documentation across teams and products - ---- - -## Why This Book Matters - -Most documentation teams struggle with: - -- Siloed tools and workflows -- Slow publishing cycles -- Poor collaboration with engineering -- Content that quickly becomes outdated - -**Docs Like Code shows you how to fix this.** - -By applying software development practices to documentation, you can: - -- Ship docs faster -- Improve accuracy and consistency -- Collaborate seamlessly with developers -- Build a sustainable, scalable documentation system - ---- - -## Who This Book Is For - -**This book is for:** -- Technical writers working with engineering teams -- Developer advocates and API documentation writers -- Teams adopting docs-as-code workflows -- Anyone using or evaluating GitHub for documentation - -**This book is not for:** -- Complete beginners with no exposure to Git or Markdown - ---- - -## What Experts Say - -> “A must-read for any technical writer looking to modernize their workflow.” - -> “Bridges the gap between writers and developers in a practical, actionable way.” - -> “One of the most useful resources on docs-as-code available today.” - ---- - -## About the Author - -Anne is a leader in developer documentation and the author of *Docs Like Code*. -She has worked extensively on API documentation, developer portals, and docs-as-code workflows across major technology organizations. - ---- - -## Preview the Book - -Want to see if it’s right for you? - -👉 Read the Quick Start Guide and explore the concepts before you buy. - -[Docs as Code Quick Start Guide](/learn/000-docs-as-code-quick-start-guide/) - ---- - -## Buy the Book - -Get your copy today: - -- Print and ebook editions available -- Ideal for individuals and teams - -👉 **Start improving your documentation workflow today** - -[Buy on Lulu](https://www.lulu.com/spotlight/justwriteclick) -[Buy on Amazon](https://amzn.to/4tiBLy6) - ---- - -## Start Building Better Documentation - -If you’re ready to modernize your documentation workflow, this book will give you the foundation. - -👉 [Why Buy the Book?](https://docslikecode.com/book/) - - -## Get Started with Docs as Code - -![Docs Like Code cover](images/docs-like-code-book.jpg){: style="padding:14px;" height="200" width="319" } - -We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out *Docs Like Code*. - -[Buy Now](https://www.lulu.com/spotlight/justwriteclick) - -## What's inside? - -**Why use GitHub for docs?** If you're unsure of a good fit for your projects and teams, read about the potential wins with these techniques. Or, you may learn how to convince others who need to hear about the use cases. - -**Information architecture and workflows, how do you choose?** Read these chapters to find out lessons learned when making sure the users are served first. - -**How can I improve upon my team's work?** Author and build content like a pro, whether you're a writer or a developer. Build in quality assurance, automate builds, and review with your teammates to make great docs. - -**What are the best practices for REST API docs?** While Swagger/OpenAPI, RAML, and other standards work well when considering the entire API lifecycle, you can also consider collaboration gains with simple markup and narrative documents beyond the REST API reference doc set. - -[Buy Now](https://www.lulu.com/spotlight/justwriteclick) - -## Who's using these docs-as-code techniques? - -> “I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long. -> -> He replied that he'd worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!” -> -> _Kelly Holcomb, Senior Technical Editor, Oracle_ - -> “This book will be the go-to guide for people looking to get into the _Docs like Code_ world. It has been on my list to write for a while, and I'm glad someone did for me. :)” -> -> _Eric Holscher, Cofounder of Read the Docs and Write the Docs_ - -> "The wonderful @annegentle introduced me to this a long while ago and Docs Like Code has been a huge improvement in /everything/. Check out https://docslikecode.com" -> -> — Cody Bunch - -> If you haven’t read about it yet I’d recommend you to read — @annegentle #DocsLikeCode #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase -> -> — Sriram Hariharan - -> #docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. -> -> — Mike Jang - -> We do this for all documentation at @GDSTeam. The brilliant @annegentle has written a book on 'docs as code' and has case studies and guidance on her website. It works so well! -> -> — Jen Lambourne - -> "Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode -> -> — Lana Brindley - -> Just finished @annegentle's new book, Docs Like Code — outstanding for devs. If you value quality docs, see the book. -> -> — Carol Willing - -> Just finished "Docs Like Code" by @annegentle — Superb advice for modern technical writing. -> -> — Doug Hellmann - -> This one just moved to the top of my reading list: a book on how to treat docs like code by @annegentle. -> -> — Patrick Andriessen