Merge pull request #177 from justwriteclick/build

July 11 main merge

Author: annegentle

_config.yml

@@ -2,7 +2,7 @@
 
 title: Let's Treat Docs Like Code
 locale: en-US
-description: Read stories, learn through practice, share with others.
+description: Technical documentation with tools and techniques like version control (GitHub) and automation (CICD) with static site generators (SSG) and more.
 logo: /images/treat-docs-like-code.png
 #url: http://127.0.0.1:4000
 url: https://www.docslikecode.com

_learn/00-github-for-docs-files.md

@@ -57,7 +57,7 @@ The terms sound confusing at first. Here's a list of vocabulary words to help yo
 
 | Term               | Definition                                                                                                                                                                                                                                                                                                                                                                                 |
 |--------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| branch             | A parallel version of a repo within the repo that does not affect the primary or master branch. You can work freely in a branch without affecting the live version. After you make changes, you can merge your branch into the master branch to publish your changes.                                                                                                                      |
+| branch             | A parallel version of a repo within the repo that does not affect the primary or main branch. You can work freely in a branch without affecting the live version. After you make changes, you can merge your branch into the main branch to publish your changes.                                                                                                                      |
 | clone              | A copy of a repo that lives on your computer instead of on a website's server.                                                                                                                                                                                                                                                                                                             |
 | commit             | A point-in-time snapshot of a repo. Commits let you see the differences between changes. A commit is an individual change to a file or set of files. Every time that you save a file or a set of files, Git creates a unique ID, also known as the SHA or hash, that tracks the changes. Commits usually contain a commit message, which is a brief description of what changes were made. |
 | downstream         | A label for a remote URL, where a remote represents a place where code is stored. A downstream remote indicates an opposite of an upstream, or original, repo.                                                                                                                                                                                                                             |
@@ -75,9 +75,9 @@ The terms sound confusing at first. Here's a list of vocabulary words to help yo
 
 You want to get a good sense of these terms, because when you're new to Git, it's easy to confuse named directories, such as a cloned fork that is named after the original repo, and Git branches.
 
-You can instruct Git to base your branch on the `master` branch in `upstream`, `origin`, or another `named` remote. For example, this command bases a new branch on the `master` branch in the `upstream` remote:
+You can instruct Git to base your branch on the `main` branch in `upstream`, `origin`, or another `named` remote. For example, this command bases a new branch on the `main` branch in the `upstream` remote:
 ```
-$ git checkout upstream/master -b my-branch
+$ git checkout upstream/main -b my-branch
 ```
 
 ## Set up prompts (Terminal on MacOS or Linux)
@@ -171,7 +171,7 @@ If you get a 404 page after logging in, then you need to be added as a collabora
    Output:
 
    ```
-   * master
+   * main
    ```
 
 Now you have a local copy of the content and can do more steps in [Working with content in GitHub repositories](https://docslikecode.com/learn/04-add-content-workflow/). Hopefully you have a good starting point for working with docs repositories.
@@ -186,7 +186,11 @@ Before you get too far writing content for a new site, get the directory set up
 ```
 $ echo "# do-docs-as-code" >> README
 ```
-1. In the root directory, initialize the Git repo.
+1. Set up your local Git installation so that it uses `main` for the default branch name every time you use the `git init` command.
+   ```bash
+   git config --global init.defaultBranch main
+   ```
+4. In the root directory, initialize the Git repo.
   ```bash
   $ git init
   ```
@@ -204,9 +208,9 @@ $ echo "# do-docs-as-code" >> README
   ```bash
   $ git remote add origin <paste the reference>
   ```
-1. In the Terminal window, set the newly added remote as the upstream branch and push the initial commit to this new remote named origin.
+1. In the Terminal window, set the newly added remote as the upstream "tracker" (named origin) and push the initial commit to this new branch named `main`.
 ```
-$ git push --set-upstream origin master
+$ git push --set-upstream origin main
 ```
 
 ## Ignoring operating system files or generated files

_posts/articles/2017-11-12-rackspace-case-study.md

@@ -103,7 +103,7 @@ At the same conference, [Rachel Whitton’s talk Delivering High-Velocity Docs t
 
 Finally, another great resource is Anne Gentle’s [Docs like Code project](https://docslikecode.com/) that aims to share information and capture best practices for creating documentation collaboratively using code systems.
 
-Are you treating docs like code, or thinking about transforming your documentation processes? We’d love to hear your thoughts and experiences. If you have questions or want to know more about contributing to Rackspace documentation, see our [Contributor Guidelines](https://rackerlabs.github.io/docs-rackspace/contributor-collateral/index.html) or e-mail us at devdoc@rackspace.com.
+Are you treating docs like code, or thinking about transforming your documentation processes? We’d love to hear your thoughts and experiences. If you have questions or want to know more about contributing to Rackspace documentation, see our [Quickstart](https://docs.rackspace.com/docs/style-guide/quickstart) or e-mail us at devdoc@rackspace.com.
 
 Originally published November 11, 2016, on the [Rackspace Blog](https://blog.rackspace.com/transforming-developer-and-support-documentation-with-docs-like-code).
 

_posts/articles/2018-02-12-change-case-study.md

@@ -13,7 +13,7 @@ comments: false
 share: true
 ---
 
-**Originally published in the [Documenting APIs: A Guide for Technical Writers on Tom Johnson's site, I'd Rather Be Writing](https://idratherbewriting.com/learnapidoc/pubapis_switching_to_docs_as_code.html). Thanks, Tom, for sharing your story in detail for others to learn.**
+**Originally published in the [Documenting APIs: A Guide for Technical Writers on Tom Johnson's site, I'd Rather Be Writing](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html). Thanks, Tom, for sharing your story in detail for others to learn.**
 
 {: .tip}
 For an overview of the docs-as-code approach, see [Docs-as-code tools](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html). In this article, I describe the challenges we faced in implementing a docs-as-code approach within a tech writing group at a large company.

_posts/articles/2018-06-05-cloudify-dont-stop-dreaming.md

@@ -8,7 +8,7 @@ author: ben_mansheim
 tags: [cicd, circleci, cloudify, Docker, docs, Hugo, Go]
 image:
   path: /images/cloudify/docs-as-code-blog-banner.png
-  caption: "[Courtesy Cloudify blog](https://cloudify.co/2018/06/05/docs-as-code-dont-stop-dreaming)"
+  caption: "[Courtesy Cloudify blog](https://cloudify.co/blog/docs-as-code-dont-stop-dreaming/)"
 comments: false
 share: true
 ---

_posts/articles/2018-10-12-platformos-1of4.md

@@ -8,7 +8,7 @@ author: diana_lakatos
 tags: [developer documentation, Design Thinking, Information Architecture, docs, documentation, UX]
 image:
   path: /images/platformos/platformos_part1/part1_cover.jpg
-  caption: "[Courtesy platformOS blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platform-os-part-1-information-architecture)"
+  caption: "[Courtesy platformOS blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platform-os-part-1-information-architecture)"
 comments: false
 share: true
 ---
@@ -89,7 +89,7 @@ Based on the Content Inventory and the results of the Card Sorting sessions, we
 
 _Sample page from our sitemap_  
 
-We have already changed some parts of our sitemap based on new information we gathered and business decisions we made. For example, we are now planning to build a separate community site, instead of having a community section on our documentation site. We decided to link to content on [platform-os.com](https://www.platform-os.com/blog/post/blog/platform-os-blog-module) (like the blog, terms & conditions, etc.) in the beginning to focus on other parts of the site, and reevaluate these sections later. We believe that both product and content development can benefit from a process that allows for such flexibility.  
+We have already changed some parts of our sitemap based on new information we gathered and business decisions we made. For example, we are now planning to build a separate community site, instead of having a community section on our documentation site. We decided to link to content on [platform-os.com](https://www.platform-os.com/blog/post/platform-os-blog-module) (like the blog, terms & conditions, etc.) in the beginning to focus on other parts of the site, and reevaluate these sections later. We believe that both product and content development can benefit from a process that allows for such flexibility.  
 
 ### Persona-based content prioritization
 
@@ -109,6 +109,6 @@ This concluded our Information Architecture phase. We have discovered and organi
 
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
-_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-1-information-architecture)._
+_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-1-information-architecture)._
 
 {% include sign-up.html %}

_posts/articles/2018-11-01-platformos-2of4.md

@@ -8,7 +8,7 @@ author: diana_lakatos
 tags: [developer documentation, Content-First Design, community, style guide, templates, editorial workflow, wireframes, docs, documentation, UX]
 image:
   path: /images/platformos/platformos_part2/part2_cover.jpg
-  caption: "[Courtesy platformOS Blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platform-os-part-2-content-production-and-layouts)"
+  caption: "[Courtesy platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platform-os-part-2-content-production-and-layouts)"
 comments: false
 share: true
 ---
@@ -142,6 +142,6 @@ We hope you enjoyed learning about how we started content production, how we bui
 
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
-_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
+_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
 
 {% include sign-up.html %}

_posts/articles/2018-11-25-platformos-3of4.md

@@ -8,7 +8,7 @@ author: diana_lakatos
 tags: [developer documentation, contributor experience, community, style guide, templates, editorial workflow, docs, documentation]
 image:
   path: /images/platformos/platformos_part3/part3_cover.jpg
-  caption: "[Courtesy platformOS Blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-3-community)"
+  caption: "[Courtesy platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-3-community)"
 comments: false
 share: true
 ---
@@ -112,6 +112,6 @@ Now that you’ve seen how we discovered the needs of our target audience, plann
 
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
-_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-3-community)._
+_This article was originally written for the [platformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-3-community)._
 
 {% include sign-up.html %}

_posts/articles/2020-02-26-platformos-4of4.md

@@ -8,12 +8,12 @@ author: diana_lakatos
 tags: [developer documentation, editorial workflow, API documentation, docs, documentation, contribution, testing, QA, performance]
 image:
   path: /images/platformos/platformos_part4/part4_cover.jpg
-  caption: "[Courtesy platformOS Blog](https://www.platformos.com/blog/post/blog/building-our-documentation-site-on-platformos-part-4-implementation)"
+  caption: "[Courtesy platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-4-implementation)"
 comments: false
 share: true
 ---
 
-In this article series we describe the process of building our [award-winning](https://www.platformos.com/blog/post/blog/platformos-developer-portal-wins-uk-technical-communication-award) developer documentation site from discovery to development, with in-depth insights into our approach, decisions, plans, and technical implementation.
+In this article series we describe the process of building our [award-winning](https://www.platformos.com/blog/post/platformos-developer-portal-wins-uk-technical-communication-award) developer documentation site from discovery to development, with in-depth insights into our approach, decisions, plans, and technical implementation.
 
 * [Part 1: Information Architecture](/articles/platformos-1of4)
 * [Part 2: Content Production and Layouts](/articles/platformos-2of4)
@@ -132,14 +132,14 @@ In the near future, we are planning to implement **performance testing with real
 
 If you’d be interested in learning more about our process and tools, check out our article series on QA and testing:  
 
-* [QA and Testing Best Practices — Part 1: Our QA Process](https://www.platformos.com/blog/post/blog/qa-and-testing-best-practices-part-1-our-qa-process)
-* [QA and Testing Best Practices — Part 2: Tips and Tricks](https://www.platformos.com/blog/post/blog/qa-and-testing-best-practices-part-2-tips-and-tricks)
-* [QA and Testing Best Practices — Part 3: Speeding Up Development and Troubleshooting](https://www.platformos.com/blog/post/blog/qa-and-testing-best-practices-part-3-speeding-up-development-and-troubleshooting)
-* [QA and Testing Best Practices — Part 4: Performance Testing](https://www.platformos.com/blog/post/blog/qa-and-testing-best-practices-part-4-performance-testing)
+* [QA and Testing Best Practices — Part 1: Our QA Process](https://www.platformos.com/blog/post/qa-and-testing-best-practices-part-1-our-qa-process)
+* [QA and Testing Best Practices — Part 2: Tips and Tricks](https://www.platformos.com/blog/post/qa-and-testing-best-practices-part-2-tips-and-tricks)
+* [QA and Testing Best Practices — Part 3: Speeding Up Development and Troubleshooting](https://www.platformos.com/blog/post/qa-and-testing-best-practices-part-3-speeding-up-development-and-troubleshooting)
+* [QA and Testing Best Practices — Part 4: Performance Testing](https://www.platformos.com/blog/post/qa-and-testing-best-practices-part-4-performance-testing)
 
 ## Performance
 
-If you read our article about [Code Quality and Performance Best Practices for Your platformOS Site](https://www.platformos.com/blog/post/blog/code-quality-and-performance-best-practices-for-your-platformos-site), you know how good performance can help you keep visitors on your site, provide the best user experience, and rank high in search results. Our documentation is a high-performance site with a Google PageSpeed Insights score of 100 for both Mobile and Desktop, so we thought it could be helpful to dive a bit deeper into what tools we use and how we achieved this amazing performance.
+If you read our article about [Code Quality and Performance Best Practices for Your platformOS Site](https://www.platformos.com/blog/post/code-quality-and-performance-best-practices-for-your-platformos-site), you know how good performance can help you keep visitors on your site, provide the best user experience, and rank high in search results. Our documentation is a high-performance site with a Google PageSpeed Insights score of 100 for both Mobile and Desktop, so we thought it could be helpful to dive a bit deeper into what tools we use and how we achieved this amazing performance.
 
 ### Measure early, measure often
 
@@ -256,7 +256,7 @@ We collect user feedback through Slack channels, the feedback block, user resear
 
 We’ve come a long way but there’s still a lot we can improve. Stay tuned, because we will write more articles to support you on your journey with platformOS.  
 
-_This article was co-authored by Pawel Kowalski, Front-End Developer and Performance Advocate at platformOS, and was originally written for the [PlatformOS Blog](https://www.platform-os.com/blog/post/blog/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
+_This article was co-authored by Pawel Kowalski, Front-End Developer and Performance Advocate at platformOS, and was originally written for the [PlatformOS Blog](https://www.platform-os.com/blog/post/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
 
 {% include sign-up.html %}
 

_posts/articles/2021-02-14-setting-up-techdocs-on-backstage.md

@@ -214,7 +214,7 @@ You will also see the content in the S3 bucket.
 
 ## Recap and summary
 
-In summary, we went through an introduction on Backstage, TechDocs, and how to publish TechDocs locally. We took a look at the cloud storage option with some screenshots showing S3. To learn more about Backstage I would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about TechDocs then [https://backstage.io/docs/features/TechDocs/TechDocs-overview](https://backstage.io/docs/features/TechDocs/TechDocs-overview) offers a great overview.
+In summary, we went through an introduction on Backstage, TechDocs, and how to publish TechDocs locally. We took a look at the cloud storage option with some screenshots showing S3. To learn more about Backstage I would recommend visiting [https://backstage.io](https://backstage.io) or if you want to learn more about TechDocs then [https://backstage.io/docs/features/techdocs/techdocs-overview](https://backstage.io/docs/features/techdocs/techdocs-overview) offers a great overview.
 
 You can also read about the gains the team at Spotify has seen since using TechDocs for all their documentation in [Ten tips for maintaining a long-term relationship with docs like code](https://www.docslikecode.com/articles/ten-tips-maintaining-long-term-docs-like-code/). TechDocs has a really nice [project board in GitHub,](https://github.com/orgs/backstage/projects/1#card-54927264) so if you're interested in working on it yourself, take a look.