Update for GitHub Pages access control link

Author: annegentle

_posts/articles/2017-04-04-balsamiq-case-study-part-1.md

@@ -1,7 +1,7 @@
 ---
 layout: post
 title: Multiple product versions - Balsamiq, Leon Barnard
-excerpt: "Learn useful techniques for static sites such as Hugo on GitHub from Leon Barnard, Designer and Writer at Balsamiq. He describes documenting multiple versions of a product with a Go coded solution."
+excerpt: "Learn useful techniques for static sites such as Hugo on GitHub from Leon Barnard, Designer and Writer at Balsamiq. He describes documenting multiple versions of a product with a Go-coded solution."
 last_modified_at: Sat May 13 18:37:07 CDT 2017
 categories: articles
 author: leon_barnard
@@ -37,7 +37,7 @@ Our product, [Balsamiq Mockups](https://balsamiq.com/), comes in multiple "flavo
 
 That's seven different products that we sell, catered to different types of users. This is great for our customers, but a challenge for our docs.
 
-The majority of our documentation is how to use one of the two core wireframe editors. Very little has to do with platform-specific features. So, seven products that we sell, but only two main sets of documentation.
+The majority of our documentation is on how to use one of the two core wireframe editors. Very little has to do with platform-specific features. So, seven products that we sell, but only two main sets of documentation.
 
 For historical reasons, most of the common documentation is in the Desktop version docs. If you used our product on a different platform, you had to know to go to the Desktop docs.
 
@@ -53,11 +53,11 @@ But, of course, we didn't want to maintain seven copies of each article. We want
 
 A simple solution, I suppose, would have been to switch from Markdown to a file format that supports including content from one file in another (like [reStructuredText](https://docutils.sourceforge.net/rst.html) or [AsciiDoc](https://asciidoc.org/)). **But, I'm stubborn** (and Hugo doesn't support them well). I like how simple Markdown is and I wanted to see if we could achieve what we wanted without abandoning it.
 
-I enlisted the help of our resident [Go](https://golang.org/) expert, [Luis](https://balsamiq.com/company/#luis), and he wrote some code to do just what we wanted. This code inside one of the Hugo templates allowed us to put help files in two hidden folders (called "\_v2" and "\_v3") that would get injected into files across multiple documentation folders each time the site was generated. The end result was that users could now find the information where they expected to find it.
+I enlisted the help of our resident [Go](https://golang.org/) expert, [Luis](https://balsamiq.com/company/#luis), and he wrote some code to do just what we wanted. This code inside one of the Hugo templates allowed us to put help files in two hidden folders (called "\_v2" and "\_v3") that would get injected into files across multiple documentation folders each time the site was generated. The result was that users could now find the information where they expected to find it.
 
 ![Content insertions]({{ site.url }}/images/balsamiq/structure5.png)
 
-Instead of changing file formats, we leveraged the flexibility of Hugo to use the meta data (front matter) from the Markdown file as a trigger to tell Hugo to insert content from one file to another.
+Instead of changing file formats, we leveraged the flexibility of Hugo to use the metadata (front matter) from the Markdown file as a trigger to tell Hugo to insert content from one file to another.
 
 The code looks like this:
 

_posts/articles/2017-04-15-balsamiq-case-study-part-3.md

@@ -5,7 +5,7 @@ excerpt: "Give list pages a makeover using Hugo, a static site generator, with s
 last_modified_at: Sat May 13 18:38:24 CDT 2017
 categories: articles
 author: leon_barnard
-tags: [case study, balsamiq, static sites, use case, wireframes, github, docs, repos, hugo, tools, gif, animated gifs]
+tags: [case study, balsamiq, static sites, use case, wireframes, GitHub, docs, repos, hugo, tools, gif, animated gifs]
 image:
   path: /images/alittlecreation-paintchips.jpg
   caption: "[Flickr alittlecreation](https://flic.kr/p/dfEUAY)"
@@ -21,7 +21,7 @@ Check out the prior two parts of this series, including [how to use conditional
 
 ## Challenge #3: Giving the list pages a makeover
 
-The last challenge is one that I had wanted to do for the first release of our new docs site, but never got around to. The challenge is that it's hard to make a documentation site look pretty beyond the home page, whether it's a static site or not.
+The last challenge is one that I had wanted to do for the first release of our new docs site but never got around to. The challenge is that it's hard to make a documentation site look pretty beyond the home page, whether it's a static site or not.
 
 Let's look at the [Dropbox help site home page](https://www.dropbox.com/help) as an example:
 
@@ -41,17 +41,17 @@ And this is exactly what we do on our documentation site within each product cat
 
 ![Previous Balsamiq Table of Contents]({{ site.url }}/images/balsamiq/desktop-toc-old.png)
 
-But I really love the look of hard-coded landing pages like the Dropbox site. The illustrations, the grid layout, the way it directs you to the information that's most important. I wanted to see if we could make our second-level pages look more like that.
+But I really love the look of hard-coded landing pages like the Dropbox site. The illustrations, the grid layout, and the way it directs you to the most important information. I wanted to see if we could make our second-level pages look more like that.
 
 To cut to the chase, here's what the upcoming version of our docs site will look like:
 
 ![New Balsamiq Table of Contents]({{ site.url }}/images/balsamiq/desktop-toc.png)
 
-It feels more like a documentation site landing page, right? It has a featured articles section with the articles that are most relevant to new users, and the rest of the articles are split evenly in three columns. Yet none of it is hard-coded, even the featured "Getting Started" articles.
+It feels more like a documentation site landing page, right? It has a featured articles section with the articles that are most relevant to new users, and the rest of the articles are split evenly into three columns. Yet none of it is hard-coded, even the featured "Getting Started" articles.
 
 I'll start by explaining the "Everything Else..." section at the bottom and what makes it different from our previous version.
 
-The links there are automatically placed by Hugo and styled using the [Bootstrap List group](https://getbootstrap.com/components/#list-group) component. That part is pretty easy. The challenge was putting them in columns and making sure that the columns were equal heights, regardless of how many articles there were.
+The links there are automatically placed by Hugo and styled using the [Bootstrap List group](https://getbootstrap.com/components/#list-group) component. That part is pretty easy. The challenge was putting them in columns and making sure that the columns were of equal heights, regardless of how many articles there were.
 
 Here's the code I wrote inside the Hugo template to define some variables to use further down in the code:
 
@@ -117,7 +117,7 @@ Voila!
 
 So, what did we learn from these challenges? I think the most important thing is that all of them were overcome without making life harder for the content writers. We didn't compromise on keeping the workflow simple when we added functionality, even though we were tempted to.
 
-We *could* have switched away from Markdown. We *could* have started writing HTML inside our Markdown files. We *could* have required manual template updates when we reordered articles. It took a lot of work not to do these things. But that's the beauty of programming: it's an up front investment that saves time and effort in the long run.
+We *could* have switched away from Markdown. We *could* have started writing HTML inside our Markdown files. We *could* have required manual template updates when we reordered articles. It took a lot of work not to do these things. But that's the beauty of programming: it's an up-front investment that saves time and effort in the long run.
 
 Static sites may seem to have more limitations than traditional CMSs or powerful technical writing tools. But if you can find a way around the limitations, you can reap the benefits that made static sites attractive in the first place. Markdown is easy. GitHub offers collaborative coding. A scripted robot can run a build command from a terminal. It's writing excellent documentation that is tough. Fortunately, that's what technical writers are good at. Having a developer liaison for the docs team can free writers from having to think about the limitations of the technology they're using so they can focus on writing the docs.
 

_posts/articles/2017-06-03-api-docs-with-code.md

@@ -15,7 +15,7 @@ share: true
 
 # A Pirate's Life for Me: Documenting APIs with Swagger
 
-Our team starting developing a new API (in C#), which I took as an opportunity to implement Swagger (now the OpenAPI Specification), an open source project used to describe and document RESTful APIs. I wanted to show our developers and support engineers that injecting documentation into the code can reduce response time, mitigate errors, and decrease the point of entry for new hires. To illustrate those gains, I needed to develop a proof of concept.
+Our team started developing a new API (in C#), which I took as an opportunity to implement Swagger (now the OpenAPI Specification), an open-source project used to describe and document RESTful APIs. I wanted to show our developers and support engineers that injecting documentation into the code can reduce response time, mitigate errors, and decrease the point of entry for new hires. To illustrate those gains, I needed to develop a proof of concept.
 
 ## Why Swagger?
 
@@ -42,7 +42,7 @@ using Swashbuckle.Swagger;
 using Swashbuckle.Swagger.XmlComments;
 ```
 
-Then, I add the following code (see example that follows), much of which is supplied in a Swashbuckle example file. In the `SwaggerGeneratorOptions` class, I specify the options that I want Swashbuckle to enable.
+Then, I add the following code (see the example that follows), much of which is supplied in a Swashbuckle example file. In the `SwaggerGeneratorOptions` class, I specify the options that I want Swashbuckle to enable.
 
 * `schemaFilters` post-modify complex schemas in the generated output. You can modify schemas for a specific member type or across all member types. The `IModelFilter` is now the `ISchemaFilter`. We created an `IModelFilter` to fix some of the generated output.
 
@@ -108,7 +108,7 @@ After enabling these options, I *could* include code that enables the Swagger UI
 
 ## Using DapperDox
 
-[DapperDox](https://dapperdox.io/) is an open source documentation framework for OpenAPI specifications. Instead of having Swashbuckle publish our API specification in the Swagger UI, I added the following code to the `Startup.cs` file. This code writes the Swagger specification to a `swagger.json` file.
+[DapperDox](https://dapperdox.io/) is an open-source documentation framework for OpenAPI specifications. Instead of having Swashbuckle publish our API specification in the Swagger UI, I added the following code to the `Startup.cs` file. This code writes the Swagger specification to a `swagger.json` file.
 
 ```csharp
    System.IO.StreamWriter file = new System.IO.StreamWriter("swagger.json");
@@ -118,7 +118,7 @@ After enabling these options, I *could* include code that enables the Swagger UI
 
 DapperDox reads this file and displays it in its own UI. I installed DapperDox and pointed it at my `swagger.json` file, and saw nothing but error messages in my command prompt.
 
-Reading through the [DapperDox documentation](https://dapperdox.io/docs/spec-resource-definitions), I discovered that *"When specifying a resource schema object...DapperDox requires that the optional schema object title member is present."* This requirement was problematic, because Swashbuckle does not include a method for adding members to a schema in the generated `swagger.json` file. Additionally, it took some tinkering in the code for me to realize that the missing title member on the `definitions` model is what caused DapperDox to break.
+Reading through the [DapperDox documentation](https://dapperdox.io/docs/spec-resource-definitions), I discovered that *"When specifying a resource schema object...DapperDox requires that the optional schema object title member is present."* This requirement was problematic because Swashbuckle does not include a method for adding members to a schema in the generated `swagger.json` file. Additionally, it took some tinkering in the code for me to realize that the missing title member on the `definitions` model is what caused DapperDox to break.
 
 ## Fixing the output
 
@@ -144,21 +144,21 @@ I compiled the code and Swashbuckle generated an updated `swagger.json` file. Wi
 .\dapperdox -spec-dir=C:\Bitbucket\APIproject\source
 ```
 
-I opened a browser and entered `http://localhost:3123`, which is where DapperDox runs by default, and it worked! DapperDox displayed my `swagger.json` file and created interactive documentation that clearly displays the requests, responses, and query parameters for the API. I demoed the output for a few developers and support engineers, and they were over the moon.
+I opened a browser and entered `http://localhost:3123`, which is where DapperDox runs by default, and it worked! DapperDox displayed my `swagger.json` file and created interactive documentation that clearly displays the requests, responses, and query parameters for the API. I demoed the output to a few developers and support engineers, and they were over the moon.
 
 ![DapperDox API reference screenshot](../../images/DapperDox_API_reference.png "DapperDox API reference screenshot")
 
 ## Next steps
 
-With this framework in place, we can extend Swashbuckle to future APIs and use DapperDox to host the `swagger.json` file for each. The resulting output lives with the code, and provides documentation that developers and support engineers can access locally by running a single command.
+With this framework in place, we can extend Swashbuckle to future APIs and use DapperDox to host the `swagger.json` file for each. The resulting output lives with the code and provides documentation that developers and support engineers can access locally by running a single command.
 
 To add documentation beyond just the generated JSON output, DapperDox works incredibly well. I can author short tutorials that describe how to integrate our API with third-party services, which developers can easily review and modify through pull requests. As the API grows, we can add a README file that describes enhancements, modifications, and new integration points. Non-API documentation will live in an `\assets` directory, which DapperDox includes at build time.
 
 Each time that the code builds, the `swagger.json` file updates with the most current information. Developers and support engineers just run the `.\dapperdox` command and specify the directory where the `swagger.json` file lives. As the code changes, so does the documentation, so technical debt approaches zero.
 
 ## Lessons learned
 
-Static site generators are all the rage, and for good reason. Providing a lightweight framework that can be deployed quickly is a huge asset when documenting APIs, especially external-facing documentation. Numerous options are available, but DapperDox felt like the right fit for our needs.
+Static site generators are all the rage and for good reason. Providing a lightweight framework that can be deployed quickly is a huge asset when documenting APIs, especially external-facing documentation. Numerous options are available, but DapperDox felt like the right fit for our needs.
 
 The pain of determining why DapperDox was broken and the additional coding required to fix the problem was worth the effort, and we are poised to integrate this process into the next set of APIs that our team develops.