diff --git a/.ruby-version b/.ruby-version index 860487c..0aec50e 100644 --- a/.ruby-version +++ b/.ruby-version @@ -1 +1 @@ -2.7.1 +3.1.4 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. 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/_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? 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 index 3e1917b..8a820ca 100644 --- a/index.html +++ b/index.html @@ -7,12 +7,33 @@ 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. In your browser, create a repository with the same name as your GitHub username, followed by "github.io". @@ -31,30 +52,89 @@
-
-Learn more +
+

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/

+
-

Learn the tools

+
+

Why Docs as Code Works

-

Learn

+

Traditional documentation:

+ -

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-as-code workflows:

+ + -
+
+

Who This Site Is For

+ +
- Docs Like Code Book +
+

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.

+
-

Buy the book

+👉 [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 %} + +--- -

Buy

+## Start Building Better Documentation -

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.

-
+If you're ready to modernize your documentation workflow: -
-

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. -

-
+👉 [Start with the Quick Start Guide](/guides/quickstart/) +👉 [Get the full book](/book/) \ No newline at end of file diff --git a/index.md.bak b/index.md.bak new file mode 100644 index 0000000..9617bcd --- /dev/null +++ b/index.md.bak @@ -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