From 304d1a0f5254f48c64d068d8d9f00d25c6b65e7a Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 17:58:20 -0500 Subject: [PATCH 01/13] Some edits and remove a link that isn't useful --- _posts/articles/2016-09-17-github-for-docs.md | 20 +++++++++---------- .../2016-09-18-github-collaborators.md | 8 ++++---- .../2016-09-23-doc-issues-tracking.md | 5 ++--- ...16-09-24-what-docs-like-code-looks-like.md | 7 +++---- .../articles/2016-11-26-remodel-your-docs.md | 11 +++++----- ...2-29-coming-soon-writing-docs-like-code.md | 2 +- .../2017-03-18-pantheon-case-study.md | 12 +++++------ .../2017-04-09-balsamiq-case-study-part-2.md | 6 +++--- 8 files changed, 34 insertions(+), 37 deletions(-) diff --git a/_posts/articles/2016-09-17-github-for-docs.md b/_posts/articles/2016-09-17-github-for-docs.md index 8bc62929..6bca969b 100644 --- a/_posts/articles/2016-09-17-github-for-docs.md +++ b/_posts/articles/2016-09-17-github-for-docs.md @@ -4,7 +4,7 @@ title: The Vocabulary of GitHub for Documentation excerpt: "What would happen if we treated docs like code?" last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [github, git, definitions, repository, branch, fork, pull request] +tags: GitHub, git, definitions, repository, branch, fork, pull request] image: path: /images/guarded-lightbulb-rob-sinclair.jpg caption: "[Flickr rob-sinclair](https://flic.kr/p/8J2gDY)" @@ -21,31 +21,31 @@ Believe me, your fellow software builders are wondering, experimenting, or alrea ![git]({{ site.url }}/images/git-logo.png) {: .pull-right} -I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web, leads to social coding, leads to social documentation. +I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web leads to social coding, leads to social documentation. # What is GitHub? ![GitHub]({{ site.url }}/images/github-logo.png) {: .pull-left} -Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for theLinux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). +Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for the Linux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). -GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. +GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. -You can keep docs in a source code repository then the developers will review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the -more treating docs like code makes sense. +You can keep docs in a source code repository then the developers will review all your changes before merging them in. Unlike traditional source code management, branches are not full copies of the entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the +more treating docs like code make sense. # GitHub definitions and parallels for information I hope I'm talking to people who care a lot about words. Let's start with some vocabulary and definitions to build upon. -* Branch: Indicator of divergence from base without changing the main line (or "trunk" if you like to visualize organic tree-structures to remember this term). -* Commit: Point-in-time snapshot of repository with changes. -* Fork (noun): Copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. +* Branch: Indicator of divergence from the base without changing the main line (or "trunk" if you like to visualize organic tree structures to remember this term). +* Commit: Point-in-time snapshot of the repository with changes. +* Fork (noun): A copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open-source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. * Fork (verb): Making a copy of the repository. * Issue: Defects, tasks, or feature requests. * Organization: Collection of group-owned repositories. -* Pull Request: Comparison of edits to see if team wants to accept changes. +* Pull Request: Comparison of edits to see if the team wants to accept changes. * Push: Move changes branch-to-branch. When you type `man git` at a Terminal prompt to read the [manual page for Git](https://www.kernel.org/pub/software/scm/git/docs/git.html), you see "Update remote refs along with associated objects," but that's more technical than we need here. * Repository: Collection of stored code or documentation that is written and built like code. * Review: Do a line-by-line comparison of a change, much like an editor would for documentation, and comment on improvements or changes. diff --git a/_posts/articles/2016-09-18-github-collaborators.md b/_posts/articles/2016-09-18-github-collaborators.md index 5a86b6f9..bf96cd29 100644 --- a/_posts/articles/2016-09-18-github-collaborators.md +++ b/_posts/articles/2016-09-18-github-collaborators.md @@ -4,7 +4,7 @@ title: Collaborating on GitHub for Documentation excerpt: "When you work with others, your deliverables win." last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [collaboration, developers, github, git, writers] +tags: [collaboration, developers, GitHub, git, writers] image: path: /images/stockholmlibrary-marcus_hansson.jpg caption: "[Flickr marcus_hansson](https://flic.kr/p/8Lrfg)" @@ -12,9 +12,9 @@ comments: false share: true --- -Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when deadlines set by development, not docs or quality assurance, so those deliverables are always squeezed for time at the end. Less context, less empathy, less collaboration. What to do? +Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when development set deadlines, not docs or quality assurance, so those deliverables are always squeezed for time in the end. Less context, less empathy, less collaboration. What to do? -All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips with each other through the documentation. +All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips through the documentation. As Andy Oram said so well in "Educating computer users: the need for community/author collaboration," "...the *value* in educational content lies in *context* (what immediate problem the reader is trying to solve) and *timeliness* (what’s true today will be outdated tomorrow)." @@ -29,7 +29,7 @@ When you write with people beyond your immediate team, ensure that those contrib * Produce effective, time-saving, user support. * Build a reputation, recruiting. -Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunity to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. +Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunities to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. If you think this all sounds nice but impractical, I encourage you to sign up for the newsletter to learn how to practice these techniques like you would a musical instrument. You need hands-on experience and time to play to get better and better. diff --git a/_posts/articles/2016-09-23-doc-issues-tracking.md b/_posts/articles/2016-09-23-doc-issues-tracking.md index 54cdfacc..b85b4f08 100644 --- a/_posts/articles/2016-09-23-doc-issues-tracking.md +++ b/_posts/articles/2016-09-23-doc-issues-tracking.md @@ -4,7 +4,7 @@ title: Quality Tracking with GitHub for Docs excerpt: "What do you do when people say, 'The Docs Suck.'?" last_modified_at: Fri Sep 23 21:03:14 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/stacked-logs-mtischendorf.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" @@ -39,7 +39,6 @@ To take it a step further, you can also add a link to edit the source doc file i In traditional enterprise doc systems, writers can go weeks without getting reviews or input. Even when asking and nagging multiple times, sometimes the documentation systems are so separate from code systems that technical reviews are through email. GASP. Put those days behind you and go where the technically knowledgeable people are. -Working in the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though in reality it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click in order to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules really well. - +Working with the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though, in reality, it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules well. {% include sign-up.html %} diff --git a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md index c639eb3e..b316afa7 100644 --- a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md +++ b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md @@ -4,7 +4,7 @@ title: Building Docs Like Code excerpt: "Let's look at a live example." last_modified_at: Sun Sep 25 15:35:08 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/threeblackdots-playground.jpg caption: "[Flickr threeblackdots](https://flic.kr/p/8tQAGQ)" @@ -13,7 +13,7 @@ comments: false share: true --- -Let's take a look at what docs like code looks like in practice. +Let's take a look at what docs as code looks like in practice. The basic steps on a Mac are: @@ -24,11 +24,10 @@ The basic steps on a Mac are: 1. Run `bundle exec jekyll serve` to serve the content from a local web server. 1. Copy and paste the `http://127.0.0.1:4000/` URL into your web browser. -This video shows you how to clone a GitHub repo with an existing Jekyll theme, and build it locally. +This video shows you how to clone a GitHub repo with an existing Jekyll theme and build it locally. ### How it's made - {% include sign-up.html %} diff --git a/_posts/articles/2016-11-26-remodel-your-docs.md b/_posts/articles/2016-11-26-remodel-your-docs.md index e8e800ca..61ed9d90 100644 --- a/_posts/articles/2016-11-26-remodel-your-docs.md +++ b/_posts/articles/2016-11-26-remodel-your-docs.md @@ -12,15 +12,15 @@ comments: false share: true --- -A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. +A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, that there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. -This house was awful. Every single surface was ugly, out-dated, and circa 1973. There was a giant hole in dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons — or was it dirt-digging armadillos? We may never know. +This house was awful. Every single surface was ugly, outdated, and circa 1973. There was a giant hole in the dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons. (Or was it dirt-digging armadillos? We may never know.) ![Raccoon visiting](../../images/trikersticks-raccoon.jpg "Raccoon visiting") Let’s look at your code base and your doc base as a great house with a good layout and foundational “bones.” You still need that “punch list” to hand to your contractor. When you move towards more docs like code techniques, make sure you treat your doc base like a code base, and track defects. Get that “punch list” done. -With a code base, you know how much remodeling you need to do. The same thinking can work well for docs. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? +With a code base, you know how much remodeling you need to do. The same thinking can work well for documentation. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? Let’s give your readers the chance to do those quality checks for you as easily as possible: by reporting the bug on the page where they found it. @@ -32,9 +32,9 @@ This technique works well when: * You want your docs to be more trustworthy by chipping away at a bug backlog. * You have a private GitHub repo for documentation, but you want to enable public bug reports with tracking back to your docs repo. -Your quick win is to look at your current docs site, any given page. Is there a way to report a bug publicly, to add to the “punch list?” +Your quick win is to look at your current docs site, on any given page. Is there a way to report a bug publicly, to add to the “punch list?” -1. Bare minimum starter level would be an email address link from every page. +1. A bare minimum starter level would be an email address link from every page. 1. Level up by adding a link to your GitHub source repo Issues page so readers can report bugs. 1. Better yet, write a quick bit of code to embed on every output doc page so that the issue is pre-filled with relevant information. @@ -44,5 +44,4 @@ Here are some resources to get your first punch in that punch list: * Using a private repo for docs, but want to track bugs publicly? Use [Issues-only Access Permissions](https://help.github.com/articles/issues-only-access-permissions/). * Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](https://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/). - {% include sign-up.html %} diff --git a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md index 7377dc57..21db22da 100644 --- a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md +++ b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md @@ -4,7 +4,7 @@ title: Coming Soon - Write Docs Like Code Ebook excerpt: "What do you want to know about these techniques?" last_modified_at: Thu Dec 29 20:07:26 CST 2016 categories: articles -tags: [ebook, epub, gitbook, book, github, docs, repos] +tags: [ebook, epub, gitbook, book, GitHub, docs, repos] image: path: /images/seabamirum-common-redpoll.jpg caption: "[Flickr seabamirum](https://flic.kr/p/dFow3k)" diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md index 3c3f7c4b..14306751 100644 --- a/_posts/articles/2017-03-18-pantheon-case-study.md +++ b/_posts/articles/2017-03-18-pantheon-case-study.md @@ -35,7 +35,7 @@ We chose to host our documentation repository on GitHub to align ourselves with #### What type of audience are you writing for? Do your readers write with you? If so, how? -Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. +Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. #### How active is your review queue? How often do you publish? @@ -43,23 +43,23 @@ The documentation project receives an average of almost 40 commits per week. The #### Do you merge or rebase? Have you kept the same workflow always? How long has the workflow been in place? -It depends. Generally, our workflow is to merge into the default branch once updates have been peer reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. +It depends. Generally, our workflow is to merge into the default branch once updates have been peer-reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. #### What's your biggest win from using GitHub for docs? Tell a story. -We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. +We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high-value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. #### What would you warn others about when thinking about GitHub for docs? -Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: checkout a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. +Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: check out a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. #### Would you suggest migrating content or only building new? It depends. We migrated a lot of content because it didn’t make sense to start over. I’d say migrate what you can but don’t be afraid to start fresh depending on the needs and goals of your project. If you do migrate, automate the process as much as possible. Your sanity will thank you. -#### Do you have automation? If so, what type or tooling, and where is the automation in the workflow? +#### Do you have automation? If so, what type of tooling, and where is the automation in the workflow? -Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub then tests and deploys changes to either a staging environment or to production. Deployments to production occur via rsync after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. +Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub and then tests and deploys changes to either a staging environment or to production. Deployments to production occur via `rsync` after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command-line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. As of March 2017, this workflow was not available to forks for security reasons. As of May 2019, [CircleCI’s documentation](https://circleci.com/docs/2.0/gh-bb-integration/) indicates there's a setting for PRs created from forked repos. diff --git a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md index 543915a4..e8159074 100644 --- a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md +++ b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md @@ -5,7 +5,7 @@ excerpt: "Learn how to play and pause animated GIFs on static sites such as Hugo last_modified_at: Sat May 13 18:37:48 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/rogerjones-wireframe.jpg caption: "[Flickr rogerjones](https://flic.kr/p/i4ZAW)" @@ -62,10 +62,10 @@ So, now, if we write: ```markdown ![gif](https://rubentd.com/img/banana.png) ``` -it triggers the gifplayer script! +it triggers the `gifplayer` script! ![party](https://rubentd.com/img/banana.gif) -Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. You can see the pause/play solution in action on our Balsamiq article on [common workarounds](https://support.balsamiq.com/tutorials/workarounds/#link-to-alternates). +Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. {% include sign-up.html %} From d084ff706e250935bd00d1948ce52d552bfcc408 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 18:25:46 -0500 Subject: [PATCH 02/13] Update for GitHub Pages access control link --- .../2017-04-04-balsamiq-case-study-part-1.md | 8 ++++---- .../2017-04-15-balsamiq-case-study-part-3.md | 12 ++++++------ _posts/articles/2017-06-03-api-docs-with-code.md | 14 +++++++------- _posts/articles/2017-08-19-when-to-wiki.md | 16 ++++++++-------- 4 files changed, 25 insertions(+), 25 deletions(-) diff --git a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md index 700b6340..a8d2175f 100644 --- a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md +++ b/_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: diff --git a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md b/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md index 6fddfa72..a58b491a 100644 --- a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md +++ b/_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. diff --git a/_posts/articles/2017-06-03-api-docs-with-code.md b/_posts/articles/2017-06-03-api-docs-with-code.md index 3c620c6e..107b2e56 100644 --- a/_posts/articles/2017-06-03-api-docs-with-code.md +++ b/_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,13 +144,13 @@ 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. @@ -158,7 +158,7 @@ Each time that the code builds, the `swagger.json` file updates with the most cu ## 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. diff --git a/_posts/articles/2017-08-19-when-to-wiki.md b/_posts/articles/2017-08-19-when-to-wiki.md index 33dfe8fd..51e23b05 100644 --- a/_posts/articles/2017-08-19-when-to-wiki.md +++ b/_posts/articles/2017-08-19-when-to-wiki.md @@ -13,7 +13,7 @@ comments: true share: true --- -While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open source, developer-centric world I was embedded in. +While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open-source, developer-centric world I was embedded in. And then, I heard from Gene in an email. @@ -21,7 +21,7 @@ And then, I heard from Gene in an email. > and get inspired to keep going. Thank you for your interesting ideas and > willingness to share them." -And he kept me going, and asking more questions as I went, and feeling energized once again to answer his question about wikis and writing closer to the code. +And he kept me going and asked more questions as I went, and I felt energized once again to answer his question about wikis and writing closer to the code. Gene goes on to share his background, which resonates with both software developers and technical writers who were once some other profession. @@ -35,11 +35,11 @@ Gene goes on to share his background, which resonates with both software develop > Markdown/reStructuredText, and looking for opportunities to make that > workflow better." -Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. +Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, a less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. We are living through change management in our content management. -He goes on to ask, with double-spaces after periods, which I find absolutely endearing, +He goes on to ask, with double-spaces after periods, which I find endearing, > "I still have companies asking about using a wiki for documentation when > considering jettisoning their legacy documentation tools, which aren't @@ -52,17 +52,17 @@ He goes on to ask, with double-spaces after periods, which I find absolutely end > "What are your thoughts on the differences between using a wiki and using > Git/Markdown, that I might be able to give them more substantive arguments?" -This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgement on either method. +This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgment on either method. -If I were in his shoes, I'd be curious and asking questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course informs your requirements list and considerations. +If I were in his shoes, I'd be curious and ask questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course, informs your requirements list and considerations. ## Consider the workflow - sit in another environment -For me, when moving towards a docs as code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. +For me, when moving towards a docs-as-code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. ## Authentication and privacy needs -Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessible only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. +Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessed only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. (Updated July 2022: refer to [Changing the visibility of your GitHub Pages site](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) for information about managing access control for your project site by publishing the site publicly or privately on Enterprise Cloud GitHub.) You can implement an authentication workflow on a site uploaded to GitHub Pages, but you then need to have the web development resources to maintain the login requirement. You could use GitHub Enterprise Pages with GitHub Enterprise requiring a VPN connection to view pages. Security and openness decisions may preclude one solution or another. From 14033cfe1ab39c0ae7492a07d404a9d6bef75d11 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 18:27:14 -0500 Subject: [PATCH 03/13] Update all github tags with GitHub --- _posts/articles/2016-11-26-remodel-your-docs.md | 2 +- _posts/articles/2017-03-18-pantheon-case-study.md | 2 +- _posts/articles/2017-03-25-symantec-case-study.md | 2 +- _posts/articles/2017-04-04-balsamiq-case-study-part-1.md | 2 +- .../articles/2018-01-06-video-presentations-docs-like-code.md | 2 +- _posts/articles/2018-02-12-change-case-study.md | 2 +- _posts/articles/2018-04-16-practical-advice.md | 2 +- .../2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_posts/articles/2016-11-26-remodel-your-docs.md b/_posts/articles/2016-11-26-remodel-your-docs.md index 61ed9d90..efb22277 100644 --- a/_posts/articles/2016-11-26-remodel-your-docs.md +++ b/_posts/articles/2016-11-26-remodel-your-docs.md @@ -4,7 +4,7 @@ title: Remodeling documentation excerpt: "Make sure you have a punch list of doc bugs to get higher quality results." last_modified_at: Sat May 13 18:34:40 CDT 2017 categories: articles -tags: [issues, bugs, technical debt, github, git, backlog] +tags: [issues, bugs, technical debt, GitHub, git, backlog] image: path: /images/mtischendorf-logpile.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md index 14306751..0ad64eff 100644 --- a/_posts/articles/2017-03-18-pantheon-case-study.md +++ b/_posts/articles/2017-03-18-pantheon-case-study.md @@ -5,7 +5,7 @@ excerpt: "In this use case, the Technical Content Editor at Pantheon, Rachel Whi last_modified_at: Sat Mar 18 09:50:27 CDT 2017 categories: articles author: rachel_whitton -tags: [case study, use case, github, docs, repos, web, content, workflows] +tags: [case study, use case, GitHub, docs, repos, web, content, workflows] image: path: /images/stevensnodgrass-bolt.jpg caption: "[Flickr stevensnodgrass](https://flic.kr/p/8jKjE2)" diff --git a/_posts/articles/2017-03-25-symantec-case-study.md b/_posts/articles/2017-03-25-symantec-case-study.md index bec271a0..f40b3b7f 100644 --- a/_posts/articles/2017-03-25-symantec-case-study.md +++ b/_posts/articles/2017-03-25-symantec-case-study.md @@ -5,7 +5,7 @@ excerpt: "Jennifer Rondeau, Technical Writing Manager at Capital One, talks abou last_modified_at: Sat Mar 25 15:51:58 CDT 2017 categories: articles author: jennifer_rondeau -tags: [case study, javadoc, doxygen, use case, github, docs, repos, workflows, tools] +tags: [case study, javadoc, doxygen, use case, GitHub, docs, repos, workflows, tools] image: path: /images/ehktang-yellow-reflection.jpg caption: "[Flickr ehktang](https://flic.kr/p/bpTk6k)" diff --git a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md index a8d2175f..9709fb2b 100644 --- a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md +++ b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md @@ -5,7 +5,7 @@ excerpt: "Learn useful techniques for static sites such as Hugo on GitHub from L last_modified_at: Sat May 13 18:37:07 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/therefore-wireframe.jpg caption: "[Flickr therefore](https://flic.kr/p/7ewunt)" diff --git a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md index 9bb5c8c6..1c37de56 100644 --- a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md +++ b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "In the last three years of Write the Docs conferences, you can learn f last_modified_at: Sat Jan 6 10:29:44 CST 2018 categories: articles author: anne_gentle -tags: [writethedocs, video, conferences, github, git, collaboration, transformation] +tags: [writethedocs, video, conferences, GitHub, git, collaboration, transformation] image: path: /images/wtd-eur-2017.jpg caption: "[Flickr writethedocs](https://flic.kr/p/LqxXHE)" diff --git a/_posts/articles/2018-02-12-change-case-study.md b/_posts/articles/2018-02-12-change-case-study.md index 6ad84c3e..769aed77 100644 --- a/_posts/articles/2018-02-12-change-case-study.md +++ b/_posts/articles/2018-02-12-change-case-study.md @@ -5,7 +5,7 @@ excerpt: Changing from a content management system to Jekyll and all the change last_modified_at: Mon Feb 12 09:06:03 CST 2018 categories: articles author: tom_johnson -tags: [engineering, security, github, git, jekyll, static site, change, culture, teamwork, collaboration, development] +tags: [engineering, security, GitHub, git, jekyll, static site, change, culture, teamwork, collaboration, development] image: path: /images/laurencehorten-traintracks.jpg caption: "[Flickr laurencehorton](https://flic.kr/p/e3AsFw)" diff --git a/_posts/articles/2018-04-16-practical-advice.md b/_posts/articles/2018-04-16-practical-advice.md index c6b3e9e1..5029fa64 100644 --- a/_posts/articles/2018-04-16-practical-advice.md +++ b/_posts/articles/2018-04-16-practical-advice.md @@ -5,7 +5,7 @@ excerpt: What does it take to publish a technical book using GitHub? Let's dig i last_modified_at: Fri Apr 20 21:01:44 CDT 2018 categories: articles author: anne_gentle -tags: [book, publishing, github, git, gitbook, lulu, self-publishing, collaboration, design, layout] +tags: [book, publishing, GitHub, git, gitbook, lulu, self-publishing, collaboration, design, layout] image: path: /images/designbyandren-lightbulb.jpg caption: "[Flickr designbyandren](https://flic.kr/p/cMiQAJ)" diff --git a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md index ed5fabd4..e686dd3a 100644 --- a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md +++ b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "Learn about one team's journey to keep a long-term relationship with t last_modified_at: Fri Nov 6 20:47:45 CST 2020 categories: articles author: gary_niemen -tags: [cicd, backstage, spotify, github, git, portal, internal, documentation, developer, docs] +tags: [cicd, backstage, spotify, GitHub, git, portal, internal, documentation, developer, docs] image: path: /images/spotify/soundboard-han.ailes.jpg caption: "[Flickr han.ailes](https://flic.kr/p/oVPTVm)" From 06ebed989e145ba5bf37bfac1a5f7bf9d56ea1fe Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 12 Jul 2022 11:34:38 -0500 Subject: [PATCH 04/13] Update with jekyll-seo-tag for canonical_url --- Gemfile | 1 + Gemfile.lock | 1 + articles/index.md | 3 --- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/Gemfile b/Gemfile index 6193a032..0d1ba16d 100644 --- a/Gemfile +++ b/Gemfile @@ -2,3 +2,4 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" gem "html-proofer" +gem "jekyll-seo-tag" \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 90987b46..1ac7e1ec 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -128,6 +128,7 @@ PLATFORMS DEPENDENCIES html-proofer + jekyll-seo-tag jekyll-theme-so-simple BUNDLED WITH diff --git a/articles/index.md b/articles/index.md index 6a41c6cb..236b9caa 100644 --- a/articles/index.md +++ b/articles/index.md @@ -5,6 +5,3 @@ excerpt: "Read articles to learn more about the docs like code vision and how to search: false entries_layout: grid --- - - -{% include sign-up.html %} From c63d43644092d2ec8a1247fd2b6c159894668d42 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 17:58:20 -0500 Subject: [PATCH 05/13] Some edits and remove a link that isn't useful --- _posts/articles/2016-09-17-github-for-docs.md | 20 +++++++++---------- .../2016-09-18-github-collaborators.md | 8 ++++---- .../2016-09-23-doc-issues-tracking.md | 5 ++--- ...16-09-24-what-docs-like-code-looks-like.md | 7 +++---- .../articles/2016-11-26-remodel-your-docs.md | 11 +++++----- ...2-29-coming-soon-writing-docs-like-code.md | 2 +- .../2017-03-18-pantheon-case-study.md | 12 +++++------ .../2017-04-09-balsamiq-case-study-part-2.md | 6 +++--- 8 files changed, 34 insertions(+), 37 deletions(-) diff --git a/_posts/articles/2016-09-17-github-for-docs.md b/_posts/articles/2016-09-17-github-for-docs.md index 8bc62929..6bca969b 100644 --- a/_posts/articles/2016-09-17-github-for-docs.md +++ b/_posts/articles/2016-09-17-github-for-docs.md @@ -4,7 +4,7 @@ title: The Vocabulary of GitHub for Documentation excerpt: "What would happen if we treated docs like code?" last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [github, git, definitions, repository, branch, fork, pull request] +tags: GitHub, git, definitions, repository, branch, fork, pull request] image: path: /images/guarded-lightbulb-rob-sinclair.jpg caption: "[Flickr rob-sinclair](https://flic.kr/p/8J2gDY)" @@ -21,31 +21,31 @@ Believe me, your fellow software builders are wondering, experimenting, or alrea ![git]({{ site.url }}/images/git-logo.png) {: .pull-right} -I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web, leads to social coding, leads to social documentation. +I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web leads to social coding, leads to social documentation. # What is GitHub? ![GitHub]({{ site.url }}/images/github-logo.png) {: .pull-left} -Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for theLinux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). +Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for the Linux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). -GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. +GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. -You can keep docs in a source code repository then the developers will review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the -more treating docs like code makes sense. +You can keep docs in a source code repository then the developers will review all your changes before merging them in. Unlike traditional source code management, branches are not full copies of the entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the +more treating docs like code make sense. # GitHub definitions and parallels for information I hope I'm talking to people who care a lot about words. Let's start with some vocabulary and definitions to build upon. -* Branch: Indicator of divergence from base without changing the main line (or "trunk" if you like to visualize organic tree-structures to remember this term). -* Commit: Point-in-time snapshot of repository with changes. -* Fork (noun): Copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. +* Branch: Indicator of divergence from the base without changing the main line (or "trunk" if you like to visualize organic tree structures to remember this term). +* Commit: Point-in-time snapshot of the repository with changes. +* Fork (noun): A copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open-source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. * Fork (verb): Making a copy of the repository. * Issue: Defects, tasks, or feature requests. * Organization: Collection of group-owned repositories. -* Pull Request: Comparison of edits to see if team wants to accept changes. +* Pull Request: Comparison of edits to see if the team wants to accept changes. * Push: Move changes branch-to-branch. When you type `man git` at a Terminal prompt to read the [manual page for Git](https://www.kernel.org/pub/software/scm/git/docs/git.html), you see "Update remote refs along with associated objects," but that's more technical than we need here. * Repository: Collection of stored code or documentation that is written and built like code. * Review: Do a line-by-line comparison of a change, much like an editor would for documentation, and comment on improvements or changes. diff --git a/_posts/articles/2016-09-18-github-collaborators.md b/_posts/articles/2016-09-18-github-collaborators.md index 5a86b6f9..bf96cd29 100644 --- a/_posts/articles/2016-09-18-github-collaborators.md +++ b/_posts/articles/2016-09-18-github-collaborators.md @@ -4,7 +4,7 @@ title: Collaborating on GitHub for Documentation excerpt: "When you work with others, your deliverables win." last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [collaboration, developers, github, git, writers] +tags: [collaboration, developers, GitHub, git, writers] image: path: /images/stockholmlibrary-marcus_hansson.jpg caption: "[Flickr marcus_hansson](https://flic.kr/p/8Lrfg)" @@ -12,9 +12,9 @@ comments: false share: true --- -Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when deadlines set by development, not docs or quality assurance, so those deliverables are always squeezed for time at the end. Less context, less empathy, less collaboration. What to do? +Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when development set deadlines, not docs or quality assurance, so those deliverables are always squeezed for time in the end. Less context, less empathy, less collaboration. What to do? -All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips with each other through the documentation. +All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips through the documentation. As Andy Oram said so well in "Educating computer users: the need for community/author collaboration," "...the *value* in educational content lies in *context* (what immediate problem the reader is trying to solve) and *timeliness* (what’s true today will be outdated tomorrow)." @@ -29,7 +29,7 @@ When you write with people beyond your immediate team, ensure that those contrib * Produce effective, time-saving, user support. * Build a reputation, recruiting. -Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunity to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. +Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunities to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. If you think this all sounds nice but impractical, I encourage you to sign up for the newsletter to learn how to practice these techniques like you would a musical instrument. You need hands-on experience and time to play to get better and better. diff --git a/_posts/articles/2016-09-23-doc-issues-tracking.md b/_posts/articles/2016-09-23-doc-issues-tracking.md index 54cdfacc..b85b4f08 100644 --- a/_posts/articles/2016-09-23-doc-issues-tracking.md +++ b/_posts/articles/2016-09-23-doc-issues-tracking.md @@ -4,7 +4,7 @@ title: Quality Tracking with GitHub for Docs excerpt: "What do you do when people say, 'The Docs Suck.'?" last_modified_at: Fri Sep 23 21:03:14 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/stacked-logs-mtischendorf.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" @@ -39,7 +39,6 @@ To take it a step further, you can also add a link to edit the source doc file i In traditional enterprise doc systems, writers can go weeks without getting reviews or input. Even when asking and nagging multiple times, sometimes the documentation systems are so separate from code systems that technical reviews are through email. GASP. Put those days behind you and go where the technically knowledgeable people are. -Working in the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though in reality it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click in order to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules really well. - +Working with the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though, in reality, it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules well. {% include sign-up.html %} diff --git a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md index c639eb3e..b316afa7 100644 --- a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md +++ b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md @@ -4,7 +4,7 @@ title: Building Docs Like Code excerpt: "Let's look at a live example." last_modified_at: Sun Sep 25 15:35:08 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/threeblackdots-playground.jpg caption: "[Flickr threeblackdots](https://flic.kr/p/8tQAGQ)" @@ -13,7 +13,7 @@ comments: false share: true --- -Let's take a look at what docs like code looks like in practice. +Let's take a look at what docs as code looks like in practice. The basic steps on a Mac are: @@ -24,11 +24,10 @@ The basic steps on a Mac are: 1. Run `bundle exec jekyll serve` to serve the content from a local web server. 1. Copy and paste the `http://127.0.0.1:4000/` URL into your web browser. -This video shows you how to clone a GitHub repo with an existing Jekyll theme, and build it locally. +This video shows you how to clone a GitHub repo with an existing Jekyll theme and build it locally. ### How it's made - {% include sign-up.html %} diff --git a/_posts/articles/2016-11-26-remodel-your-docs.md b/_posts/articles/2016-11-26-remodel-your-docs.md index e8e800ca..61ed9d90 100644 --- a/_posts/articles/2016-11-26-remodel-your-docs.md +++ b/_posts/articles/2016-11-26-remodel-your-docs.md @@ -12,15 +12,15 @@ comments: false share: true --- -A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. +A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, that there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. -This house was awful. Every single surface was ugly, out-dated, and circa 1973. There was a giant hole in dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons — or was it dirt-digging armadillos? We may never know. +This house was awful. Every single surface was ugly, outdated, and circa 1973. There was a giant hole in the dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons. (Or was it dirt-digging armadillos? We may never know.) ![Raccoon visiting](../../images/trikersticks-raccoon.jpg "Raccoon visiting") Let’s look at your code base and your doc base as a great house with a good layout and foundational “bones.” You still need that “punch list” to hand to your contractor. When you move towards more docs like code techniques, make sure you treat your doc base like a code base, and track defects. Get that “punch list” done. -With a code base, you know how much remodeling you need to do. The same thinking can work well for docs. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? +With a code base, you know how much remodeling you need to do. The same thinking can work well for documentation. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? Let’s give your readers the chance to do those quality checks for you as easily as possible: by reporting the bug on the page where they found it. @@ -32,9 +32,9 @@ This technique works well when: * You want your docs to be more trustworthy by chipping away at a bug backlog. * You have a private GitHub repo for documentation, but you want to enable public bug reports with tracking back to your docs repo. -Your quick win is to look at your current docs site, any given page. Is there a way to report a bug publicly, to add to the “punch list?” +Your quick win is to look at your current docs site, on any given page. Is there a way to report a bug publicly, to add to the “punch list?” -1. Bare minimum starter level would be an email address link from every page. +1. A bare minimum starter level would be an email address link from every page. 1. Level up by adding a link to your GitHub source repo Issues page so readers can report bugs. 1. Better yet, write a quick bit of code to embed on every output doc page so that the issue is pre-filled with relevant information. @@ -44,5 +44,4 @@ Here are some resources to get your first punch in that punch list: * Using a private repo for docs, but want to track bugs publicly? Use [Issues-only Access Permissions](https://help.github.com/articles/issues-only-access-permissions/). * Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](https://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/). - {% include sign-up.html %} diff --git a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md index 7377dc57..21db22da 100644 --- a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md +++ b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md @@ -4,7 +4,7 @@ title: Coming Soon - Write Docs Like Code Ebook excerpt: "What do you want to know about these techniques?" last_modified_at: Thu Dec 29 20:07:26 CST 2016 categories: articles -tags: [ebook, epub, gitbook, book, github, docs, repos] +tags: [ebook, epub, gitbook, book, GitHub, docs, repos] image: path: /images/seabamirum-common-redpoll.jpg caption: "[Flickr seabamirum](https://flic.kr/p/dFow3k)" diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md index 3c3f7c4b..14306751 100644 --- a/_posts/articles/2017-03-18-pantheon-case-study.md +++ b/_posts/articles/2017-03-18-pantheon-case-study.md @@ -35,7 +35,7 @@ We chose to host our documentation repository on GitHub to align ourselves with #### What type of audience are you writing for? Do your readers write with you? If so, how? -Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. +Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. #### How active is your review queue? How often do you publish? @@ -43,23 +43,23 @@ The documentation project receives an average of almost 40 commits per week. The #### Do you merge or rebase? Have you kept the same workflow always? How long has the workflow been in place? -It depends. Generally, our workflow is to merge into the default branch once updates have been peer reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. +It depends. Generally, our workflow is to merge into the default branch once updates have been peer-reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. #### What's your biggest win from using GitHub for docs? Tell a story. -We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. +We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high-value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. #### What would you warn others about when thinking about GitHub for docs? -Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: checkout a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. +Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: check out a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. #### Would you suggest migrating content or only building new? It depends. We migrated a lot of content because it didn’t make sense to start over. I’d say migrate what you can but don’t be afraid to start fresh depending on the needs and goals of your project. If you do migrate, automate the process as much as possible. Your sanity will thank you. -#### Do you have automation? If so, what type or tooling, and where is the automation in the workflow? +#### Do you have automation? If so, what type of tooling, and where is the automation in the workflow? -Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub then tests and deploys changes to either a staging environment or to production. Deployments to production occur via rsync after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. +Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub and then tests and deploys changes to either a staging environment or to production. Deployments to production occur via `rsync` after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command-line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. As of March 2017, this workflow was not available to forks for security reasons. As of May 2019, [CircleCI’s documentation](https://circleci.com/docs/2.0/gh-bb-integration/) indicates there's a setting for PRs created from forked repos. diff --git a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md index 543915a4..e8159074 100644 --- a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md +++ b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md @@ -5,7 +5,7 @@ excerpt: "Learn how to play and pause animated GIFs on static sites such as Hugo last_modified_at: Sat May 13 18:37:48 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/rogerjones-wireframe.jpg caption: "[Flickr rogerjones](https://flic.kr/p/i4ZAW)" @@ -62,10 +62,10 @@ So, now, if we write: ```markdown ![gif](https://rubentd.com/img/banana.png) ``` -it triggers the gifplayer script! +it triggers the `gifplayer` script! ![party](https://rubentd.com/img/banana.gif) -Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. You can see the pause/play solution in action on our Balsamiq article on [common workarounds](https://support.balsamiq.com/tutorials/workarounds/#link-to-alternates). +Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. {% include sign-up.html %} From dd71e40c6fff70f69557610bab7258eee46da56e Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 18:25:46 -0500 Subject: [PATCH 06/13] Update for GitHub Pages access control link --- .../2017-04-04-balsamiq-case-study-part-1.md | 8 ++++---- .../2017-04-15-balsamiq-case-study-part-3.md | 12 ++++++------ _posts/articles/2017-06-03-api-docs-with-code.md | 14 +++++++------- _posts/articles/2017-08-19-when-to-wiki.md | 16 ++++++++-------- 4 files changed, 25 insertions(+), 25 deletions(-) diff --git a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md index 700b6340..a8d2175f 100644 --- a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md +++ b/_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: diff --git a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md b/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md index 6fddfa72..a58b491a 100644 --- a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md +++ b/_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. diff --git a/_posts/articles/2017-06-03-api-docs-with-code.md b/_posts/articles/2017-06-03-api-docs-with-code.md index 3c620c6e..107b2e56 100644 --- a/_posts/articles/2017-06-03-api-docs-with-code.md +++ b/_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,13 +144,13 @@ 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. @@ -158,7 +158,7 @@ Each time that the code builds, the `swagger.json` file updates with the most cu ## 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. diff --git a/_posts/articles/2017-08-19-when-to-wiki.md b/_posts/articles/2017-08-19-when-to-wiki.md index 33dfe8fd..51e23b05 100644 --- a/_posts/articles/2017-08-19-when-to-wiki.md +++ b/_posts/articles/2017-08-19-when-to-wiki.md @@ -13,7 +13,7 @@ comments: true share: true --- -While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open source, developer-centric world I was embedded in. +While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open-source, developer-centric world I was embedded in. And then, I heard from Gene in an email. @@ -21,7 +21,7 @@ And then, I heard from Gene in an email. > and get inspired to keep going. Thank you for your interesting ideas and > willingness to share them." -And he kept me going, and asking more questions as I went, and feeling energized once again to answer his question about wikis and writing closer to the code. +And he kept me going and asked more questions as I went, and I felt energized once again to answer his question about wikis and writing closer to the code. Gene goes on to share his background, which resonates with both software developers and technical writers who were once some other profession. @@ -35,11 +35,11 @@ Gene goes on to share his background, which resonates with both software develop > Markdown/reStructuredText, and looking for opportunities to make that > workflow better." -Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. +Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, a less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. We are living through change management in our content management. -He goes on to ask, with double-spaces after periods, which I find absolutely endearing, +He goes on to ask, with double-spaces after periods, which I find endearing, > "I still have companies asking about using a wiki for documentation when > considering jettisoning their legacy documentation tools, which aren't @@ -52,17 +52,17 @@ He goes on to ask, with double-spaces after periods, which I find absolutely end > "What are your thoughts on the differences between using a wiki and using > Git/Markdown, that I might be able to give them more substantive arguments?" -This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgement on either method. +This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgment on either method. -If I were in his shoes, I'd be curious and asking questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course informs your requirements list and considerations. +If I were in his shoes, I'd be curious and ask questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course, informs your requirements list and considerations. ## Consider the workflow - sit in another environment -For me, when moving towards a docs as code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. +For me, when moving towards a docs-as-code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. ## Authentication and privacy needs -Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessible only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. +Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessed only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. (Updated July 2022: refer to [Changing the visibility of your GitHub Pages site](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) for information about managing access control for your project site by publishing the site publicly or privately on Enterprise Cloud GitHub.) You can implement an authentication workflow on a site uploaded to GitHub Pages, but you then need to have the web development resources to maintain the login requirement. You could use GitHub Enterprise Pages with GitHub Enterprise requiring a VPN connection to view pages. Security and openness decisions may preclude one solution or another. From a82a0aa1ae8f50dc3bcf43b9dd641accfe05eea4 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 18:27:14 -0500 Subject: [PATCH 07/13] Update all github tags with GitHub --- _posts/articles/2016-11-26-remodel-your-docs.md | 2 +- _posts/articles/2017-03-18-pantheon-case-study.md | 2 +- _posts/articles/2017-03-25-symantec-case-study.md | 2 +- _posts/articles/2017-04-04-balsamiq-case-study-part-1.md | 2 +- .../articles/2018-01-06-video-presentations-docs-like-code.md | 2 +- _posts/articles/2018-02-12-change-case-study.md | 2 +- _posts/articles/2018-04-16-practical-advice.md | 2 +- .../2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_posts/articles/2016-11-26-remodel-your-docs.md b/_posts/articles/2016-11-26-remodel-your-docs.md index 61ed9d90..efb22277 100644 --- a/_posts/articles/2016-11-26-remodel-your-docs.md +++ b/_posts/articles/2016-11-26-remodel-your-docs.md @@ -4,7 +4,7 @@ title: Remodeling documentation excerpt: "Make sure you have a punch list of doc bugs to get higher quality results." last_modified_at: Sat May 13 18:34:40 CDT 2017 categories: articles -tags: [issues, bugs, technical debt, github, git, backlog] +tags: [issues, bugs, technical debt, GitHub, git, backlog] image: path: /images/mtischendorf-logpile.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md index 14306751..0ad64eff 100644 --- a/_posts/articles/2017-03-18-pantheon-case-study.md +++ b/_posts/articles/2017-03-18-pantheon-case-study.md @@ -5,7 +5,7 @@ excerpt: "In this use case, the Technical Content Editor at Pantheon, Rachel Whi last_modified_at: Sat Mar 18 09:50:27 CDT 2017 categories: articles author: rachel_whitton -tags: [case study, use case, github, docs, repos, web, content, workflows] +tags: [case study, use case, GitHub, docs, repos, web, content, workflows] image: path: /images/stevensnodgrass-bolt.jpg caption: "[Flickr stevensnodgrass](https://flic.kr/p/8jKjE2)" diff --git a/_posts/articles/2017-03-25-symantec-case-study.md b/_posts/articles/2017-03-25-symantec-case-study.md index bec271a0..f40b3b7f 100644 --- a/_posts/articles/2017-03-25-symantec-case-study.md +++ b/_posts/articles/2017-03-25-symantec-case-study.md @@ -5,7 +5,7 @@ excerpt: "Jennifer Rondeau, Technical Writing Manager at Capital One, talks abou last_modified_at: Sat Mar 25 15:51:58 CDT 2017 categories: articles author: jennifer_rondeau -tags: [case study, javadoc, doxygen, use case, github, docs, repos, workflows, tools] +tags: [case study, javadoc, doxygen, use case, GitHub, docs, repos, workflows, tools] image: path: /images/ehktang-yellow-reflection.jpg caption: "[Flickr ehktang](https://flic.kr/p/bpTk6k)" diff --git a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md index a8d2175f..9709fb2b 100644 --- a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md +++ b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md @@ -5,7 +5,7 @@ excerpt: "Learn useful techniques for static sites such as Hugo on GitHub from L last_modified_at: Sat May 13 18:37:07 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/therefore-wireframe.jpg caption: "[Flickr therefore](https://flic.kr/p/7ewunt)" diff --git a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md index 9bb5c8c6..1c37de56 100644 --- a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md +++ b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "In the last three years of Write the Docs conferences, you can learn f last_modified_at: Sat Jan 6 10:29:44 CST 2018 categories: articles author: anne_gentle -tags: [writethedocs, video, conferences, github, git, collaboration, transformation] +tags: [writethedocs, video, conferences, GitHub, git, collaboration, transformation] image: path: /images/wtd-eur-2017.jpg caption: "[Flickr writethedocs](https://flic.kr/p/LqxXHE)" diff --git a/_posts/articles/2018-02-12-change-case-study.md b/_posts/articles/2018-02-12-change-case-study.md index 6ad84c3e..769aed77 100644 --- a/_posts/articles/2018-02-12-change-case-study.md +++ b/_posts/articles/2018-02-12-change-case-study.md @@ -5,7 +5,7 @@ excerpt: Changing from a content management system to Jekyll and all the change last_modified_at: Mon Feb 12 09:06:03 CST 2018 categories: articles author: tom_johnson -tags: [engineering, security, github, git, jekyll, static site, change, culture, teamwork, collaboration, development] +tags: [engineering, security, GitHub, git, jekyll, static site, change, culture, teamwork, collaboration, development] image: path: /images/laurencehorten-traintracks.jpg caption: "[Flickr laurencehorton](https://flic.kr/p/e3AsFw)" diff --git a/_posts/articles/2018-04-16-practical-advice.md b/_posts/articles/2018-04-16-practical-advice.md index c6b3e9e1..5029fa64 100644 --- a/_posts/articles/2018-04-16-practical-advice.md +++ b/_posts/articles/2018-04-16-practical-advice.md @@ -5,7 +5,7 @@ excerpt: What does it take to publish a technical book using GitHub? Let's dig i last_modified_at: Fri Apr 20 21:01:44 CDT 2018 categories: articles author: anne_gentle -tags: [book, publishing, github, git, gitbook, lulu, self-publishing, collaboration, design, layout] +tags: [book, publishing, GitHub, git, gitbook, lulu, self-publishing, collaboration, design, layout] image: path: /images/designbyandren-lightbulb.jpg caption: "[Flickr designbyandren](https://flic.kr/p/cMiQAJ)" diff --git a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md index ed5fabd4..e686dd3a 100644 --- a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md +++ b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "Learn about one team's journey to keep a long-term relationship with t last_modified_at: Fri Nov 6 20:47:45 CST 2020 categories: articles author: gary_niemen -tags: [cicd, backstage, spotify, github, git, portal, internal, documentation, developer, docs] +tags: [cicd, backstage, spotify, GitHub, git, portal, internal, documentation, developer, docs] image: path: /images/spotify/soundboard-han.ailes.jpg caption: "[Flickr han.ailes](https://flic.kr/p/oVPTVm)" From 2b5e0feb0a232d4727f5018128782d3ad5dc5c77 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 12 Jul 2022 11:34:38 -0500 Subject: [PATCH 08/13] Update with jekyll-seo-tag for canonical_url --- Gemfile | 1 + Gemfile.lock | 1 + articles/index.md | 3 --- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/Gemfile b/Gemfile index 6193a032..0d1ba16d 100644 --- a/Gemfile +++ b/Gemfile @@ -2,3 +2,4 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" gem "html-proofer" +gem "jekyll-seo-tag" \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 90987b46..1ac7e1ec 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -128,6 +128,7 @@ PLATFORMS DEPENDENCIES html-proofer + jekyll-seo-tag jekyll-theme-so-simple BUNDLED WITH diff --git a/articles/index.md b/articles/index.md index 6a41c6cb..236b9caa 100644 --- a/articles/index.md +++ b/articles/index.md @@ -5,6 +5,3 @@ excerpt: "Read articles to learn more about the docs like code vision and how to search: false entries_layout: grid --- - - -{% include sign-up.html %} From 24722fd0a7038795cf6f93d9f4269a13cebefd34 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 12 Jul 2022 11:48:04 -0500 Subject: [PATCH 09/13] Update _config.yml with jekyll-seo-tag for canonical_url to work --- Gemfile | 1 - _config.yml | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index 0d1ba16d..6193a032 100644 --- a/Gemfile +++ b/Gemfile @@ -2,4 +2,3 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" gem "html-proofer" -gem "jekyll-seo-tag" \ No newline at end of file diff --git a/_config.yml b/_config.yml index 8b0754dd..e5b19af3 100644 --- a/_config.yml +++ b/_config.yml @@ -29,6 +29,7 @@ plugins: - jekyll-sitemap - jekyll-gist - jekyll-feed + - jekyll-seo-tag google_fonts: - name: "Source Sans Pro" weights: "400,400i,700,700i" From 6e3c02ca8ac3d496489bd8dad9d834b1f1d635b4 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 17:58:20 -0500 Subject: [PATCH 10/13] Update with jekyll-seo-tag for canonical_url --- Gemfile | 1 + Gemfile.lock | 1 + _config.yml | 1 + _posts/articles/2016-09-17-github-for-docs.md | 20 +++++++++---------- .../2016-09-18-github-collaborators.md | 8 ++++---- .../2016-09-23-doc-issues-tracking.md | 5 ++--- ...16-09-24-what-docs-like-code-looks-like.md | 7 +++---- .../articles/2016-11-26-remodel-your-docs.md | 13 ++++++------ ...2-29-coming-soon-writing-docs-like-code.md | 2 +- .../2017-03-18-pantheon-case-study.md | 14 ++++++------- .../2017-03-25-symantec-case-study.md | 2 +- .../2017-04-04-balsamiq-case-study-part-1.md | 10 +++++----- .../2017-04-09-balsamiq-case-study-part-2.md | 6 +++--- .../2017-04-15-balsamiq-case-study-part-3.md | 12 +++++------ .../articles/2017-06-03-api-docs-with-code.md | 14 ++++++------- _posts/articles/2017-08-19-when-to-wiki.md | 16 +++++++-------- ...1-06-video-presentations-docs-like-code.md | 2 +- .../articles/2018-02-12-change-case-study.md | 2 +- .../articles/2018-04-16-practical-advice.md | 2 +- ...ps-maintaining-long-term-docs-like-code.md | 2 +- articles/index.md | 3 --- 21 files changed, 70 insertions(+), 73 deletions(-) diff --git a/Gemfile b/Gemfile index 6193a032..0d1ba16d 100644 --- a/Gemfile +++ b/Gemfile @@ -2,3 +2,4 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" gem "html-proofer" +gem "jekyll-seo-tag" \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 90987b46..1ac7e1ec 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -128,6 +128,7 @@ PLATFORMS DEPENDENCIES html-proofer + jekyll-seo-tag jekyll-theme-so-simple BUNDLED WITH diff --git a/_config.yml b/_config.yml index 8b0754dd..e5b19af3 100644 --- a/_config.yml +++ b/_config.yml @@ -29,6 +29,7 @@ plugins: - jekyll-sitemap - jekyll-gist - jekyll-feed + - jekyll-seo-tag google_fonts: - name: "Source Sans Pro" weights: "400,400i,700,700i" diff --git a/_posts/articles/2016-09-17-github-for-docs.md b/_posts/articles/2016-09-17-github-for-docs.md index 8bc62929..6bca969b 100644 --- a/_posts/articles/2016-09-17-github-for-docs.md +++ b/_posts/articles/2016-09-17-github-for-docs.md @@ -4,7 +4,7 @@ title: The Vocabulary of GitHub for Documentation excerpt: "What would happen if we treated docs like code?" last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [github, git, definitions, repository, branch, fork, pull request] +tags: GitHub, git, definitions, repository, branch, fork, pull request] image: path: /images/guarded-lightbulb-rob-sinclair.jpg caption: "[Flickr rob-sinclair](https://flic.kr/p/8J2gDY)" @@ -21,31 +21,31 @@ Believe me, your fellow software builders are wondering, experimenting, or alrea ![git]({{ site.url }}/images/git-logo.png) {: .pull-right} -I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web, leads to social coding, leads to social documentation. +I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web leads to social coding, leads to social documentation. # What is GitHub? ![GitHub]({{ site.url }}/images/github-logo.png) {: .pull-left} -Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for theLinux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). +Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for the Linux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). -GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. +GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. -You can keep docs in a source code repository then the developers will review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the -more treating docs like code makes sense. +You can keep docs in a source code repository then the developers will review all your changes before merging them in. Unlike traditional source code management, branches are not full copies of the entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the +more treating docs like code make sense. # GitHub definitions and parallels for information I hope I'm talking to people who care a lot about words. Let's start with some vocabulary and definitions to build upon. -* Branch: Indicator of divergence from base without changing the main line (or "trunk" if you like to visualize organic tree-structures to remember this term). -* Commit: Point-in-time snapshot of repository with changes. -* Fork (noun): Copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. +* Branch: Indicator of divergence from the base without changing the main line (or "trunk" if you like to visualize organic tree structures to remember this term). +* Commit: Point-in-time snapshot of the repository with changes. +* Fork (noun): A copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open-source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. * Fork (verb): Making a copy of the repository. * Issue: Defects, tasks, or feature requests. * Organization: Collection of group-owned repositories. -* Pull Request: Comparison of edits to see if team wants to accept changes. +* Pull Request: Comparison of edits to see if the team wants to accept changes. * Push: Move changes branch-to-branch. When you type `man git` at a Terminal prompt to read the [manual page for Git](https://www.kernel.org/pub/software/scm/git/docs/git.html), you see "Update remote refs along with associated objects," but that's more technical than we need here. * Repository: Collection of stored code or documentation that is written and built like code. * Review: Do a line-by-line comparison of a change, much like an editor would for documentation, and comment on improvements or changes. diff --git a/_posts/articles/2016-09-18-github-collaborators.md b/_posts/articles/2016-09-18-github-collaborators.md index 5a86b6f9..bf96cd29 100644 --- a/_posts/articles/2016-09-18-github-collaborators.md +++ b/_posts/articles/2016-09-18-github-collaborators.md @@ -4,7 +4,7 @@ title: Collaborating on GitHub for Documentation excerpt: "When you work with others, your deliverables win." last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [collaboration, developers, github, git, writers] +tags: [collaboration, developers, GitHub, git, writers] image: path: /images/stockholmlibrary-marcus_hansson.jpg caption: "[Flickr marcus_hansson](https://flic.kr/p/8Lrfg)" @@ -12,9 +12,9 @@ comments: false share: true --- -Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when deadlines set by development, not docs or quality assurance, so those deliverables are always squeezed for time at the end. Less context, less empathy, less collaboration. What to do? +Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when development set deadlines, not docs or quality assurance, so those deliverables are always squeezed for time in the end. Less context, less empathy, less collaboration. What to do? -All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips with each other through the documentation. +All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips through the documentation. As Andy Oram said so well in "Educating computer users: the need for community/author collaboration," "...the *value* in educational content lies in *context* (what immediate problem the reader is trying to solve) and *timeliness* (what’s true today will be outdated tomorrow)." @@ -29,7 +29,7 @@ When you write with people beyond your immediate team, ensure that those contrib * Produce effective, time-saving, user support. * Build a reputation, recruiting. -Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunity to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. +Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunities to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. If you think this all sounds nice but impractical, I encourage you to sign up for the newsletter to learn how to practice these techniques like you would a musical instrument. You need hands-on experience and time to play to get better and better. diff --git a/_posts/articles/2016-09-23-doc-issues-tracking.md b/_posts/articles/2016-09-23-doc-issues-tracking.md index 54cdfacc..b85b4f08 100644 --- a/_posts/articles/2016-09-23-doc-issues-tracking.md +++ b/_posts/articles/2016-09-23-doc-issues-tracking.md @@ -4,7 +4,7 @@ title: Quality Tracking with GitHub for Docs excerpt: "What do you do when people say, 'The Docs Suck.'?" last_modified_at: Fri Sep 23 21:03:14 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/stacked-logs-mtischendorf.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" @@ -39,7 +39,6 @@ To take it a step further, you can also add a link to edit the source doc file i In traditional enterprise doc systems, writers can go weeks without getting reviews or input. Even when asking and nagging multiple times, sometimes the documentation systems are so separate from code systems that technical reviews are through email. GASP. Put those days behind you and go where the technically knowledgeable people are. -Working in the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though in reality it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click in order to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules really well. - +Working with the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though, in reality, it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules well. {% include sign-up.html %} diff --git a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md index c639eb3e..b316afa7 100644 --- a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md +++ b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md @@ -4,7 +4,7 @@ title: Building Docs Like Code excerpt: "Let's look at a live example." last_modified_at: Sun Sep 25 15:35:08 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/threeblackdots-playground.jpg caption: "[Flickr threeblackdots](https://flic.kr/p/8tQAGQ)" @@ -13,7 +13,7 @@ comments: false share: true --- -Let's take a look at what docs like code looks like in practice. +Let's take a look at what docs as code looks like in practice. The basic steps on a Mac are: @@ -24,11 +24,10 @@ The basic steps on a Mac are: 1. Run `bundle exec jekyll serve` to serve the content from a local web server. 1. Copy and paste the `http://127.0.0.1:4000/` URL into your web browser. -This video shows you how to clone a GitHub repo with an existing Jekyll theme, and build it locally. +This video shows you how to clone a GitHub repo with an existing Jekyll theme and build it locally. ### How it's made - {% include sign-up.html %} diff --git a/_posts/articles/2016-11-26-remodel-your-docs.md b/_posts/articles/2016-11-26-remodel-your-docs.md index e8e800ca..efb22277 100644 --- a/_posts/articles/2016-11-26-remodel-your-docs.md +++ b/_posts/articles/2016-11-26-remodel-your-docs.md @@ -4,7 +4,7 @@ title: Remodeling documentation excerpt: "Make sure you have a punch list of doc bugs to get higher quality results." last_modified_at: Sat May 13 18:34:40 CDT 2017 categories: articles -tags: [issues, bugs, technical debt, github, git, backlog] +tags: [issues, bugs, technical debt, GitHub, git, backlog] image: path: /images/mtischendorf-logpile.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" @@ -12,15 +12,15 @@ comments: false share: true --- -A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. +A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, that there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. -This house was awful. Every single surface was ugly, out-dated, and circa 1973. There was a giant hole in dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons — or was it dirt-digging armadillos? We may never know. +This house was awful. Every single surface was ugly, outdated, and circa 1973. There was a giant hole in the dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons. (Or was it dirt-digging armadillos? We may never know.) ![Raccoon visiting](../../images/trikersticks-raccoon.jpg "Raccoon visiting") Let’s look at your code base and your doc base as a great house with a good layout and foundational “bones.” You still need that “punch list” to hand to your contractor. When you move towards more docs like code techniques, make sure you treat your doc base like a code base, and track defects. Get that “punch list” done. -With a code base, you know how much remodeling you need to do. The same thinking can work well for docs. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? +With a code base, you know how much remodeling you need to do. The same thinking can work well for documentation. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? Let’s give your readers the chance to do those quality checks for you as easily as possible: by reporting the bug on the page where they found it. @@ -32,9 +32,9 @@ This technique works well when: * You want your docs to be more trustworthy by chipping away at a bug backlog. * You have a private GitHub repo for documentation, but you want to enable public bug reports with tracking back to your docs repo. -Your quick win is to look at your current docs site, any given page. Is there a way to report a bug publicly, to add to the “punch list?” +Your quick win is to look at your current docs site, on any given page. Is there a way to report a bug publicly, to add to the “punch list?” -1. Bare minimum starter level would be an email address link from every page. +1. A bare minimum starter level would be an email address link from every page. 1. Level up by adding a link to your GitHub source repo Issues page so readers can report bugs. 1. Better yet, write a quick bit of code to embed on every output doc page so that the issue is pre-filled with relevant information. @@ -44,5 +44,4 @@ Here are some resources to get your first punch in that punch list: * Using a private repo for docs, but want to track bugs publicly? Use [Issues-only Access Permissions](https://help.github.com/articles/issues-only-access-permissions/). * Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](https://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/). - {% include sign-up.html %} diff --git a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md index 7377dc57..21db22da 100644 --- a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md +++ b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md @@ -4,7 +4,7 @@ title: Coming Soon - Write Docs Like Code Ebook excerpt: "What do you want to know about these techniques?" last_modified_at: Thu Dec 29 20:07:26 CST 2016 categories: articles -tags: [ebook, epub, gitbook, book, github, docs, repos] +tags: [ebook, epub, gitbook, book, GitHub, docs, repos] image: path: /images/seabamirum-common-redpoll.jpg caption: "[Flickr seabamirum](https://flic.kr/p/dFow3k)" diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md index 3c3f7c4b..0ad64eff 100644 --- a/_posts/articles/2017-03-18-pantheon-case-study.md +++ b/_posts/articles/2017-03-18-pantheon-case-study.md @@ -5,7 +5,7 @@ excerpt: "In this use case, the Technical Content Editor at Pantheon, Rachel Whi last_modified_at: Sat Mar 18 09:50:27 CDT 2017 categories: articles author: rachel_whitton -tags: [case study, use case, github, docs, repos, web, content, workflows] +tags: [case study, use case, GitHub, docs, repos, web, content, workflows] image: path: /images/stevensnodgrass-bolt.jpg caption: "[Flickr stevensnodgrass](https://flic.kr/p/8jKjE2)" @@ -35,7 +35,7 @@ We chose to host our documentation repository on GitHub to align ourselves with #### What type of audience are you writing for? Do your readers write with you? If so, how? -Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. +Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. #### How active is your review queue? How often do you publish? @@ -43,23 +43,23 @@ The documentation project receives an average of almost 40 commits per week. The #### Do you merge or rebase? Have you kept the same workflow always? How long has the workflow been in place? -It depends. Generally, our workflow is to merge into the default branch once updates have been peer reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. +It depends. Generally, our workflow is to merge into the default branch once updates have been peer-reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. #### What's your biggest win from using GitHub for docs? Tell a story. -We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. +We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high-value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. #### What would you warn others about when thinking about GitHub for docs? -Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: checkout a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. +Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: check out a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. #### Would you suggest migrating content or only building new? It depends. We migrated a lot of content because it didn’t make sense to start over. I’d say migrate what you can but don’t be afraid to start fresh depending on the needs and goals of your project. If you do migrate, automate the process as much as possible. Your sanity will thank you. -#### Do you have automation? If so, what type or tooling, and where is the automation in the workflow? +#### Do you have automation? If so, what type of tooling, and where is the automation in the workflow? -Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub then tests and deploys changes to either a staging environment or to production. Deployments to production occur via rsync after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. +Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub and then tests and deploys changes to either a staging environment or to production. Deployments to production occur via `rsync` after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command-line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. As of March 2017, this workflow was not available to forks for security reasons. As of May 2019, [CircleCI’s documentation](https://circleci.com/docs/2.0/gh-bb-integration/) indicates there's a setting for PRs created from forked repos. diff --git a/_posts/articles/2017-03-25-symantec-case-study.md b/_posts/articles/2017-03-25-symantec-case-study.md index bec271a0..f40b3b7f 100644 --- a/_posts/articles/2017-03-25-symantec-case-study.md +++ b/_posts/articles/2017-03-25-symantec-case-study.md @@ -5,7 +5,7 @@ excerpt: "Jennifer Rondeau, Technical Writing Manager at Capital One, talks abou last_modified_at: Sat Mar 25 15:51:58 CDT 2017 categories: articles author: jennifer_rondeau -tags: [case study, javadoc, doxygen, use case, github, docs, repos, workflows, tools] +tags: [case study, javadoc, doxygen, use case, GitHub, docs, repos, workflows, tools] image: path: /images/ehktang-yellow-reflection.jpg caption: "[Flickr ehktang](https://flic.kr/p/bpTk6k)" diff --git a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md index 700b6340..9709fb2b 100644 --- a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md +++ b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md @@ -1,11 +1,11 @@ --- 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 -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/therefore-wireframe.jpg caption: "[Flickr therefore](https://flic.kr/p/7ewunt)" @@ -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: diff --git a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md index 543915a4..e8159074 100644 --- a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md +++ b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md @@ -5,7 +5,7 @@ excerpt: "Learn how to play and pause animated GIFs on static sites such as Hugo last_modified_at: Sat May 13 18:37:48 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/rogerjones-wireframe.jpg caption: "[Flickr rogerjones](https://flic.kr/p/i4ZAW)" @@ -62,10 +62,10 @@ So, now, if we write: ```markdown ![gif](https://rubentd.com/img/banana.png) ``` -it triggers the gifplayer script! +it triggers the `gifplayer` script! ![party](https://rubentd.com/img/banana.gif) -Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. You can see the pause/play solution in action on our Balsamiq article on [common workarounds](https://support.balsamiq.com/tutorials/workarounds/#link-to-alternates). +Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. {% include sign-up.html %} diff --git a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md b/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md index 6fddfa72..a58b491a 100644 --- a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md +++ b/_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. diff --git a/_posts/articles/2017-06-03-api-docs-with-code.md b/_posts/articles/2017-06-03-api-docs-with-code.md index 3c620c6e..107b2e56 100644 --- a/_posts/articles/2017-06-03-api-docs-with-code.md +++ b/_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,13 +144,13 @@ 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. @@ -158,7 +158,7 @@ Each time that the code builds, the `swagger.json` file updates with the most cu ## 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. diff --git a/_posts/articles/2017-08-19-when-to-wiki.md b/_posts/articles/2017-08-19-when-to-wiki.md index 33dfe8fd..51e23b05 100644 --- a/_posts/articles/2017-08-19-when-to-wiki.md +++ b/_posts/articles/2017-08-19-when-to-wiki.md @@ -13,7 +13,7 @@ comments: true share: true --- -While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open source, developer-centric world I was embedded in. +While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open-source, developer-centric world I was embedded in. And then, I heard from Gene in an email. @@ -21,7 +21,7 @@ And then, I heard from Gene in an email. > and get inspired to keep going. Thank you for your interesting ideas and > willingness to share them." -And he kept me going, and asking more questions as I went, and feeling energized once again to answer his question about wikis and writing closer to the code. +And he kept me going and asked more questions as I went, and I felt energized once again to answer his question about wikis and writing closer to the code. Gene goes on to share his background, which resonates with both software developers and technical writers who were once some other profession. @@ -35,11 +35,11 @@ Gene goes on to share his background, which resonates with both software develop > Markdown/reStructuredText, and looking for opportunities to make that > workflow better." -Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. +Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, a less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. We are living through change management in our content management. -He goes on to ask, with double-spaces after periods, which I find absolutely endearing, +He goes on to ask, with double-spaces after periods, which I find endearing, > "I still have companies asking about using a wiki for documentation when > considering jettisoning their legacy documentation tools, which aren't @@ -52,17 +52,17 @@ He goes on to ask, with double-spaces after periods, which I find absolutely end > "What are your thoughts on the differences between using a wiki and using > Git/Markdown, that I might be able to give them more substantive arguments?" -This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgement on either method. +This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgment on either method. -If I were in his shoes, I'd be curious and asking questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course informs your requirements list and considerations. +If I were in his shoes, I'd be curious and ask questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course, informs your requirements list and considerations. ## Consider the workflow - sit in another environment -For me, when moving towards a docs as code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. +For me, when moving towards a docs-as-code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. ## Authentication and privacy needs -Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessible only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. +Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessed only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. (Updated July 2022: refer to [Changing the visibility of your GitHub Pages site](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) for information about managing access control for your project site by publishing the site publicly or privately on Enterprise Cloud GitHub.) You can implement an authentication workflow on a site uploaded to GitHub Pages, but you then need to have the web development resources to maintain the login requirement. You could use GitHub Enterprise Pages with GitHub Enterprise requiring a VPN connection to view pages. Security and openness decisions may preclude one solution or another. diff --git a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md index 9bb5c8c6..1c37de56 100644 --- a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md +++ b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "In the last three years of Write the Docs conferences, you can learn f last_modified_at: Sat Jan 6 10:29:44 CST 2018 categories: articles author: anne_gentle -tags: [writethedocs, video, conferences, github, git, collaboration, transformation] +tags: [writethedocs, video, conferences, GitHub, git, collaboration, transformation] image: path: /images/wtd-eur-2017.jpg caption: "[Flickr writethedocs](https://flic.kr/p/LqxXHE)" diff --git a/_posts/articles/2018-02-12-change-case-study.md b/_posts/articles/2018-02-12-change-case-study.md index 6ad84c3e..769aed77 100644 --- a/_posts/articles/2018-02-12-change-case-study.md +++ b/_posts/articles/2018-02-12-change-case-study.md @@ -5,7 +5,7 @@ excerpt: Changing from a content management system to Jekyll and all the change last_modified_at: Mon Feb 12 09:06:03 CST 2018 categories: articles author: tom_johnson -tags: [engineering, security, github, git, jekyll, static site, change, culture, teamwork, collaboration, development] +tags: [engineering, security, GitHub, git, jekyll, static site, change, culture, teamwork, collaboration, development] image: path: /images/laurencehorten-traintracks.jpg caption: "[Flickr laurencehorton](https://flic.kr/p/e3AsFw)" diff --git a/_posts/articles/2018-04-16-practical-advice.md b/_posts/articles/2018-04-16-practical-advice.md index c6b3e9e1..5029fa64 100644 --- a/_posts/articles/2018-04-16-practical-advice.md +++ b/_posts/articles/2018-04-16-practical-advice.md @@ -5,7 +5,7 @@ excerpt: What does it take to publish a technical book using GitHub? Let's dig i last_modified_at: Fri Apr 20 21:01:44 CDT 2018 categories: articles author: anne_gentle -tags: [book, publishing, github, git, gitbook, lulu, self-publishing, collaboration, design, layout] +tags: [book, publishing, GitHub, git, gitbook, lulu, self-publishing, collaboration, design, layout] image: path: /images/designbyandren-lightbulb.jpg caption: "[Flickr designbyandren](https://flic.kr/p/cMiQAJ)" diff --git a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md index ed5fabd4..e686dd3a 100644 --- a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md +++ b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "Learn about one team's journey to keep a long-term relationship with t last_modified_at: Fri Nov 6 20:47:45 CST 2020 categories: articles author: gary_niemen -tags: [cicd, backstage, spotify, github, git, portal, internal, documentation, developer, docs] +tags: [cicd, backstage, spotify, GitHub, git, portal, internal, documentation, developer, docs] image: path: /images/spotify/soundboard-han.ailes.jpg caption: "[Flickr han.ailes](https://flic.kr/p/oVPTVm)" diff --git a/articles/index.md b/articles/index.md index 6a41c6cb..236b9caa 100644 --- a/articles/index.md +++ b/articles/index.md @@ -5,6 +5,3 @@ excerpt: "Read articles to learn more about the docs like code vision and how to search: false entries_layout: grid --- - - -{% include sign-up.html %} From 061d9a3405004c69a118097a35b0f787e0132674 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 12 Jul 2022 12:08:03 -0500 Subject: [PATCH 11/13] Update authors file --- _data/authors.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/_data/authors.yml b/_data/authors.yml index 61d4c224..d447a20f 100644 --- a/_data/authors.yml +++ b/_data/authors.yml @@ -76,3 +76,10 @@ padraig_o_brien: github: //github.com/padraigobrien twitter: padraigobrien bio: "Director of engineering" + +radhikapc: + name: Radhika Puthiyetath + picture: https://docslikecode.com/images/radhika-sysdig.png + github: //github.com/radhikapc + twitter: radhikapc + bio: "Principal Technical Writer" From e7af55080490b336a0fc24836afdc85b4a1bdf39 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 11 Jul 2022 17:58:20 -0500 Subject: [PATCH 12/13] Update with jekyll-seo-tag for canonical_url Update authors file --- Gemfile | 1 + Gemfile.lock | 1 + _config.yml | 1 + _data/authors.yml | 7 +++++++ _posts/articles/2016-09-17-github-for-docs.md | 20 +++++++++---------- .../2016-09-18-github-collaborators.md | 8 ++++---- .../2016-09-23-doc-issues-tracking.md | 5 ++--- ...16-09-24-what-docs-like-code-looks-like.md | 7 +++---- .../articles/2016-11-26-remodel-your-docs.md | 13 ++++++------ ...2-29-coming-soon-writing-docs-like-code.md | 2 +- .../2017-03-18-pantheon-case-study.md | 14 ++++++------- .../2017-03-25-symantec-case-study.md | 2 +- .../2017-04-04-balsamiq-case-study-part-1.md | 10 +++++----- .../2017-04-09-balsamiq-case-study-part-2.md | 6 +++--- .../2017-04-15-balsamiq-case-study-part-3.md | 12 +++++------ .../articles/2017-06-03-api-docs-with-code.md | 14 ++++++------- _posts/articles/2017-08-19-when-to-wiki.md | 16 +++++++-------- ...1-06-video-presentations-docs-like-code.md | 2 +- .../articles/2018-02-12-change-case-study.md | 2 +- .../articles/2018-04-16-practical-advice.md | 2 +- ...ps-maintaining-long-term-docs-like-code.md | 2 +- articles/index.md | 3 --- 22 files changed, 77 insertions(+), 73 deletions(-) diff --git a/Gemfile b/Gemfile index 6193a032..0d1ba16d 100644 --- a/Gemfile +++ b/Gemfile @@ -2,3 +2,4 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" gem "html-proofer" +gem "jekyll-seo-tag" \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 90987b46..1ac7e1ec 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -128,6 +128,7 @@ PLATFORMS DEPENDENCIES html-proofer + jekyll-seo-tag jekyll-theme-so-simple BUNDLED WITH diff --git a/_config.yml b/_config.yml index 8b0754dd..e5b19af3 100644 --- a/_config.yml +++ b/_config.yml @@ -29,6 +29,7 @@ plugins: - jekyll-sitemap - jekyll-gist - jekyll-feed + - jekyll-seo-tag google_fonts: - name: "Source Sans Pro" weights: "400,400i,700,700i" diff --git a/_data/authors.yml b/_data/authors.yml index 61d4c224..d447a20f 100644 --- a/_data/authors.yml +++ b/_data/authors.yml @@ -76,3 +76,10 @@ padraig_o_brien: github: //github.com/padraigobrien twitter: padraigobrien bio: "Director of engineering" + +radhikapc: + name: Radhika Puthiyetath + picture: https://docslikecode.com/images/radhika-sysdig.png + github: //github.com/radhikapc + twitter: radhikapc + bio: "Principal Technical Writer" diff --git a/_posts/articles/2016-09-17-github-for-docs.md b/_posts/articles/2016-09-17-github-for-docs.md index 8bc62929..6bca969b 100644 --- a/_posts/articles/2016-09-17-github-for-docs.md +++ b/_posts/articles/2016-09-17-github-for-docs.md @@ -4,7 +4,7 @@ title: The Vocabulary of GitHub for Documentation excerpt: "What would happen if we treated docs like code?" last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [github, git, definitions, repository, branch, fork, pull request] +tags: GitHub, git, definitions, repository, branch, fork, pull request] image: path: /images/guarded-lightbulb-rob-sinclair.jpg caption: "[Flickr rob-sinclair](https://flic.kr/p/8J2gDY)" @@ -21,31 +21,31 @@ Believe me, your fellow software builders are wondering, experimenting, or alrea ![git]({{ site.url }}/images/git-logo.png) {: .pull-right} -I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web, leads to social coding, leads to social documentation. +I’ve found that the principles inherent to the social web for coding work extremely well for documentation. The social web leads to social coding, leads to social documentation. # What is GitHub? ![GitHub]({{ site.url }}/images/github-logo.png) {: .pull-left} -Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for theLinux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). +Like many tools, git and GitHub were created by fire — through a pressing need for performant and efficient source control management for the Linux kernel. Read the history in the excellent [Pro Git Book](https://git-scm.com/book/en/v2/Getting-Started-A-Short-History-of-Git). -GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. +GitHub is the web interface for `git` the command-line tool, that works well on Linux, Mac, or Windows. To work with others on a project (code or docs), you merge files. This model is the opposite of using a “lock and checkout” model, where no one else can work on the piece at the same time as you. With GitHub, you can work separately and bring it all together later. Git has a non-linear branching model that can take some learning to get used to. That said, I've found git and GitHub for docs quite practical and even inspirational. -You can keep docs in a source code repository then the developers will review all your changes prior to merging them in. Unlike traditional source code management, branches are not full copies of entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the -more treating docs like code makes sense. +You can keep docs in a source code repository then the developers will review all your changes before merging them in. Unlike traditional source code management, branches are not full copies of the entire code base so they are “cheap” and “fast.” The more Agile techniques are applied to documentation, the +more treating docs like code make sense. # GitHub definitions and parallels for information I hope I'm talking to people who care a lot about words. Let's start with some vocabulary and definitions to build upon. -* Branch: Indicator of divergence from base without changing the main line (or "trunk" if you like to visualize organic tree-structures to remember this term). -* Commit: Point-in-time snapshot of repository with changes. -* Fork (noun): Copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. +* Branch: Indicator of divergence from the base without changing the main line (or "trunk" if you like to visualize organic tree structures to remember this term). +* Commit: Point-in-time snapshot of the repository with changes. +* Fork (noun): A copy of the repository that is entirely yours in your namespace. In GitHub-land, forking does not have a negative connotation that it can in other contexts (such as taking an open-source project in a new direction in a huff to get different contributors). Rather, it is a way to contribute openly and publicly with your account attributed. * Fork (verb): Making a copy of the repository. * Issue: Defects, tasks, or feature requests. * Organization: Collection of group-owned repositories. -* Pull Request: Comparison of edits to see if team wants to accept changes. +* Pull Request: Comparison of edits to see if the team wants to accept changes. * Push: Move changes branch-to-branch. When you type `man git` at a Terminal prompt to read the [manual page for Git](https://www.kernel.org/pub/software/scm/git/docs/git.html), you see "Update remote refs along with associated objects," but that's more technical than we need here. * Repository: Collection of stored code or documentation that is written and built like code. * Review: Do a line-by-line comparison of a change, much like an editor would for documentation, and comment on improvements or changes. diff --git a/_posts/articles/2016-09-18-github-collaborators.md b/_posts/articles/2016-09-18-github-collaborators.md index 5a86b6f9..bf96cd29 100644 --- a/_posts/articles/2016-09-18-github-collaborators.md +++ b/_posts/articles/2016-09-18-github-collaborators.md @@ -4,7 +4,7 @@ title: Collaborating on GitHub for Documentation excerpt: "When you work with others, your deliverables win." last_modified_at: Sat Sep 17 07:11:52 CDT 2016 categories: articles -tags: [collaboration, developers, github, git, writers] +tags: [collaboration, developers, GitHub, git, writers] image: path: /images/stockholmlibrary-marcus_hansson.jpg caption: "[Flickr marcus_hansson](https://flic.kr/p/8Lrfg)" @@ -12,9 +12,9 @@ comments: false share: true --- -Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when deadlines set by development, not docs or quality assurance, so those deliverables are always squeezed for time at the end. Less context, less empathy, less collaboration. What to do? +Let's admit it. Writing in isolation sucks. No one to bounce ideas off of, to tell you when you're flat-out wrong or a terrible typist. Happens in organizations all the time: assignments thrown over a wall, deliverables that are project-centric instead of user-centric. The hardest can be when development set deadlines, not docs or quality assurance, so those deliverables are always squeezed for time in the end. Less context, less empathy, less collaboration. What to do? -All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips with each other through the documentation. +All these downfalls can be avoided when you collaborate where your readers and makers live—on GitHub. I say, go beyond content curation and curate the audience itself! Write with and for the audience. Have a developer write for her fellow developers. Make sure users have a way to share tips through the documentation. As Andy Oram said so well in "Educating computer users: the need for community/author collaboration," "...the *value* in educational content lies in *context* (what immediate problem the reader is trying to solve) and *timeliness* (what’s true today will be outdated tomorrow)." @@ -29,7 +29,7 @@ When you write with people beyond your immediate team, ensure that those contrib * Produce effective, time-saving, user support. * Build a reputation, recruiting. -Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunity to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. +Harnessing these needs being met is not about gaining free labor. Contributors should be highly, highly valued, and rewarded. It's about creating opportunities to shine, and curating jobs. Because contributor graphs are available on GitHub, and because the contribution data can be mined to see that reputation being built one pull request at a time, GitHub gives rewards in a new way. If you think this all sounds nice but impractical, I encourage you to sign up for the newsletter to learn how to practice these techniques like you would a musical instrument. You need hands-on experience and time to play to get better and better. diff --git a/_posts/articles/2016-09-23-doc-issues-tracking.md b/_posts/articles/2016-09-23-doc-issues-tracking.md index 54cdfacc..b85b4f08 100644 --- a/_posts/articles/2016-09-23-doc-issues-tracking.md +++ b/_posts/articles/2016-09-23-doc-issues-tracking.md @@ -4,7 +4,7 @@ title: Quality Tracking with GitHub for Docs excerpt: "What do you do when people say, 'The Docs Suck.'?" last_modified_at: Fri Sep 23 21:03:14 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/stacked-logs-mtischendorf.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" @@ -39,7 +39,6 @@ To take it a step further, you can also add a link to edit the source doc file i In traditional enterprise doc systems, writers can go weeks without getting reviews or input. Even when asking and nagging multiple times, sometimes the documentation systems are so separate from code systems that technical reviews are through email. GASP. Put those days behind you and go where the technically knowledgeable people are. -Working in the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though in reality it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click in order to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules really well. - +Working with the same collaboration tools as technical people gives better reviews. We can merge as many as 50 patches per day, though, in reality, it's about a dozen a day. We are running up to four automated doc tests per patch and requiring two humans to check the patch and click to publish. Each reviewer who can publish must adhere to our review rules, and people follow the rules well. {% include sign-up.html %} diff --git a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md index c639eb3e..b316afa7 100644 --- a/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md +++ b/_posts/articles/2016-09-24-what-docs-like-code-looks-like.md @@ -4,7 +4,7 @@ title: Building Docs Like Code excerpt: "Let's look at a live example." last_modified_at: Sun Sep 25 15:35:08 CDT 2016 categories: articles -tags: [developers, github, git, improvement, quality, testing, writers] +tags: [developers, GitHub, git, improvement, quality, testing, writers] image: path: /images/threeblackdots-playground.jpg caption: "[Flickr threeblackdots](https://flic.kr/p/8tQAGQ)" @@ -13,7 +13,7 @@ comments: false share: true --- -Let's take a look at what docs like code looks like in practice. +Let's take a look at what docs as code looks like in practice. The basic steps on a Mac are: @@ -24,11 +24,10 @@ The basic steps on a Mac are: 1. Run `bundle exec jekyll serve` to serve the content from a local web server. 1. Copy and paste the `http://127.0.0.1:4000/` URL into your web browser. -This video shows you how to clone a GitHub repo with an existing Jekyll theme, and build it locally. +This video shows you how to clone a GitHub repo with an existing Jekyll theme and build it locally. ### How it's made - {% include sign-up.html %} diff --git a/_posts/articles/2016-11-26-remodel-your-docs.md b/_posts/articles/2016-11-26-remodel-your-docs.md index e8e800ca..efb22277 100644 --- a/_posts/articles/2016-11-26-remodel-your-docs.md +++ b/_posts/articles/2016-11-26-remodel-your-docs.md @@ -4,7 +4,7 @@ title: Remodeling documentation excerpt: "Make sure you have a punch list of doc bugs to get higher quality results." last_modified_at: Sat May 13 18:34:40 CDT 2017 categories: articles -tags: [issues, bugs, technical debt, github, git, backlog] +tags: [issues, bugs, technical debt, GitHub, git, backlog] image: path: /images/mtischendorf-logpile.jpg caption: "[Flickr mtischendorf](https://flic.kr/p/aAb4s8)" @@ -12,15 +12,15 @@ comments: false share: true --- -A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. +A few years ago we went house-hunting in Austin, Texas. One house was so popular during the first showing, that there were six back-to-back appointments. We waited in the driveway while another couple toured it. Once they left, we could quickly go through it while another prospective buyer waited on the front walkway. -This house was awful. Every single surface was ugly, out-dated, and circa 1973. There was a giant hole in dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons — or was it dirt-digging armadillos? We may never know. +This house was awful. Every single surface was ugly, outdated, and circa 1973. There was a giant hole in the dirt by the front porch, likely dug by an animal. But you know what? I loved it. I wanted to bring it back to a vibrant family home, taking it back from the rogue porch-dwelling raccoons. (Or was it dirt-digging armadillos? We may never know.) ![Raccoon visiting](../../images/trikersticks-raccoon.jpg "Raccoon visiting") Let’s look at your code base and your doc base as a great house with a good layout and foundational “bones.” You still need that “punch list” to hand to your contractor. When you move towards more docs like code techniques, make sure you treat your doc base like a code base, and track defects. Get that “punch list” done. -With a code base, you know how much remodeling you need to do. The same thinking can work well for docs. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? +With a code base, you know how much remodeling you need to do. The same thinking can work well for documentation. How dated have your docs become? How accurate are the docs compared to the rest of the code base? How can you make the site livable and vibrant again? Let’s give your readers the chance to do those quality checks for you as easily as possible: by reporting the bug on the page where they found it. @@ -32,9 +32,9 @@ This technique works well when: * You want your docs to be more trustworthy by chipping away at a bug backlog. * You have a private GitHub repo for documentation, but you want to enable public bug reports with tracking back to your docs repo. -Your quick win is to look at your current docs site, any given page. Is there a way to report a bug publicly, to add to the “punch list?” +Your quick win is to look at your current docs site, on any given page. Is there a way to report a bug publicly, to add to the “punch list?” -1. Bare minimum starter level would be an email address link from every page. +1. A bare minimum starter level would be an email address link from every page. 1. Level up by adding a link to your GitHub source repo Issues page so readers can report bugs. 1. Better yet, write a quick bit of code to embed on every output doc page so that the issue is pre-filled with relevant information. @@ -44,5 +44,4 @@ Here are some resources to get your first punch in that punch list: * Using a private repo for docs, but want to track bugs publicly? Use [Issues-only Access Permissions](https://help.github.com/articles/issues-only-access-permissions/). * Want to add a bit of code to pre-create Issues to use as comments on every page? Free yourself from Disqus comments. Try this [set of tips and sample code in a blog post](https://zpbappi.com/jekyll-with-tags-archive-and-comments-in-github-pages/). - {% include sign-up.html %} diff --git a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md index 7377dc57..21db22da 100644 --- a/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md +++ b/_posts/articles/2016-12-29-coming-soon-writing-docs-like-code.md @@ -4,7 +4,7 @@ title: Coming Soon - Write Docs Like Code Ebook excerpt: "What do you want to know about these techniques?" last_modified_at: Thu Dec 29 20:07:26 CST 2016 categories: articles -tags: [ebook, epub, gitbook, book, github, docs, repos] +tags: [ebook, epub, gitbook, book, GitHub, docs, repos] image: path: /images/seabamirum-common-redpoll.jpg caption: "[Flickr seabamirum](https://flic.kr/p/dFow3k)" diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md index 3c3f7c4b..0ad64eff 100644 --- a/_posts/articles/2017-03-18-pantheon-case-study.md +++ b/_posts/articles/2017-03-18-pantheon-case-study.md @@ -5,7 +5,7 @@ excerpt: "In this use case, the Technical Content Editor at Pantheon, Rachel Whi last_modified_at: Sat Mar 18 09:50:27 CDT 2017 categories: articles author: rachel_whitton -tags: [case study, use case, github, docs, repos, web, content, workflows] +tags: [case study, use case, GitHub, docs, repos, web, content, workflows] image: path: /images/stevensnodgrass-bolt.jpg caption: "[Flickr stevensnodgrass](https://flic.kr/p/8jKjE2)" @@ -35,7 +35,7 @@ We chose to host our documentation repository on GitHub to align ourselves with #### What type of audience are you writing for? Do your readers write with you? If so, how? -Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. +Pantheon’s audience for documentation consists primarily of developers and technical advocates for digital agencies. Public contributions are most often initiated from a call to action on the site. Visitors start by clicking the Contribute button, then either edit the current page, report an issue, or suggest new content. Depending on the selection, a new tab for GitHub will open to either edit the page or open an issue using a pre-filled template. [We encourage all contributors to create a profile](https://github.com/pantheon-systems/documentation/blob/master/CONTRIBUTING.md#contributors) and attribute their work alongside any pull requests. #### How active is your review queue? How often do you publish? @@ -43,23 +43,23 @@ The documentation project receives an average of almost 40 commits per week. The #### Do you merge or rebase? Have you kept the same workflow always? How long has the workflow been in place? -It depends. Generally, our workflow is to merge into the default branch once updates have been peer reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. +It depends. Generally, our workflow is to merge into the default branch once updates have been peer-reviewed on a “feature” branch. We use rebase as needed or as an alternative to merging when including work in progress from one feature branch on another during their simultaneous development to ensure changes are aligned and accounted for. Our workflow is constantly evolving to better serve the project. #### What's your biggest win from using GitHub for docs? Tell a story. -We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. +We try our best to prevent gaps in documentation, but one area that’s really challenging for us is covering external integrations. I didn’t know it at the time, but making the move to GitHub set us up to receive high-value contributions from other organizations. Chris Tietzel, CEO and Founder of Lockr, submitted an article (https://pantheon.io/docs/guides/lockr/) to the docs via GitHub after receiving support requests from users for help installing and integrating Lockr on Pantheon-hosted websites. #### What would you warn others about when thinking about GitHub for docs? -Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: checkout a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. +Think about the contributor and moderator experiences - don’t be afraid to adjust workflows as your project matures. Be aware that moderators won’t have write access to forks unless granted by the maintainer of the fork - this means you’ll need to have a plan for copy edits on Pull Requests from a fork that are initiated from non-org members. We handle these by using GitHub’s suggested workflow for merging locally on the command line: check out a new branch, pull commits from the fork, make copy edits, stage and commit, switch to the default branch, then merge and push to GitHub. The Pull Request will update to reflect its merged status within the default branch. #### Would you suggest migrating content or only building new? It depends. We migrated a lot of content because it didn’t make sense to start over. I’d say migrate what you can but don’t be afraid to start fresh depending on the needs and goals of your project. If you do migrate, automate the process as much as possible. Your sanity will thank you. -#### Do you have automation? If so, what type or tooling, and where is the automation in the workflow? +#### Do you have automation? If so, what type of tooling, and where is the automation in the workflow? -Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub then tests and deploys changes to either a staging environment or to production. Deployments to production occur via rsync after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. +Pantheon uses CircleCI for continuous integration which builds all commits pushed to GitHub and then tests and deploys changes to either a staging environment or to production. Deployments to production occur via `rsync` after tests have run successfully. If any test fails (broken link, performance regression, etc.) The build will fail on CircleCI and the deployment to production is skipped until a passing build occurs. Branches other than our default branch get deployed to isolated cloud development environments for staging with unique and publicly accessible URLs. Deployments to staging environments happen before the test suite is run to help debug issues and/or failures. Once builds have been deployed to a staging environment, a comment is created on the commit in GitHub with a link to the changes for quick and easy peer review. Once a feature branch has been merged into the default, the associated staging environment is automatically deleted along with the branch. The automation procedures are scripted in Bash and configured in the `circle.yml` file within the project’s root directory. The staging environments are created using Pantheon’s command-line tool, [Terminus](https://pantheon.io/docs/terminus/), and our [Multidev](https://pantheon.io/features/multidev-cloud-environments) feature. As of March 2017, this workflow was not available to forks for security reasons. As of May 2019, [CircleCI’s documentation](https://circleci.com/docs/2.0/gh-bb-integration/) indicates there's a setting for PRs created from forked repos. diff --git a/_posts/articles/2017-03-25-symantec-case-study.md b/_posts/articles/2017-03-25-symantec-case-study.md index bec271a0..f40b3b7f 100644 --- a/_posts/articles/2017-03-25-symantec-case-study.md +++ b/_posts/articles/2017-03-25-symantec-case-study.md @@ -5,7 +5,7 @@ excerpt: "Jennifer Rondeau, Technical Writing Manager at Capital One, talks abou last_modified_at: Sat Mar 25 15:51:58 CDT 2017 categories: articles author: jennifer_rondeau -tags: [case study, javadoc, doxygen, use case, github, docs, repos, workflows, tools] +tags: [case study, javadoc, doxygen, use case, GitHub, docs, repos, workflows, tools] image: path: /images/ehktang-yellow-reflection.jpg caption: "[Flickr ehktang](https://flic.kr/p/bpTk6k)" diff --git a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md index 700b6340..9709fb2b 100644 --- a/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md +++ b/_posts/articles/2017-04-04-balsamiq-case-study-part-1.md @@ -1,11 +1,11 @@ --- 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 -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/therefore-wireframe.jpg caption: "[Flickr therefore](https://flic.kr/p/7ewunt)" @@ -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: diff --git a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md index 543915a4..e8159074 100644 --- a/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md +++ b/_posts/articles/2017-04-09-balsamiq-case-study-part-2.md @@ -5,7 +5,7 @@ excerpt: "Learn how to play and pause animated GIFs on static sites such as Hugo last_modified_at: Sat May 13 18:37:48 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/rogerjones-wireframe.jpg caption: "[Flickr rogerjones](https://flic.kr/p/i4ZAW)" @@ -62,10 +62,10 @@ So, now, if we write: ```markdown ![gif](https://rubentd.com/img/banana.png) ``` -it triggers the gifplayer script! +it triggers the `gifplayer` script! ![party](https://rubentd.com/img/banana.gif) -Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. You can see the pause/play solution in action on our Balsamiq article on [common workarounds](https://support.balsamiq.com/tutorials/workarounds/#link-to-alternates). +Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing. {% include sign-up.html %} diff --git a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md b/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md index 6fddfa72..a58b491a 100644 --- a/_posts/articles/2017-04-15-balsamiq-case-study-part-3.md +++ b/_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. diff --git a/_posts/articles/2017-06-03-api-docs-with-code.md b/_posts/articles/2017-06-03-api-docs-with-code.md index 3c620c6e..107b2e56 100644 --- a/_posts/articles/2017-06-03-api-docs-with-code.md +++ b/_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,13 +144,13 @@ 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. @@ -158,7 +158,7 @@ Each time that the code builds, the `swagger.json` file updates with the most cu ## 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. diff --git a/_posts/articles/2017-08-19-when-to-wiki.md b/_posts/articles/2017-08-19-when-to-wiki.md index 33dfe8fd..51e23b05 100644 --- a/_posts/articles/2017-08-19-when-to-wiki.md +++ b/_posts/articles/2017-08-19-when-to-wiki.md @@ -13,7 +13,7 @@ comments: true share: true --- -While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open source, developer-centric world I was embedded in. +While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open-source, developer-centric world I was embedded in. And then, I heard from Gene in an email. @@ -21,7 +21,7 @@ And then, I heard from Gene in an email. > and get inspired to keep going. Thank you for your interesting ideas and > willingness to share them." -And he kept me going, and asking more questions as I went, and feeling energized once again to answer his question about wikis and writing closer to the code. +And he kept me going and asked more questions as I went, and I felt energized once again to answer his question about wikis and writing closer to the code. Gene goes on to share his background, which resonates with both software developers and technical writers who were once some other profession. @@ -35,11 +35,11 @@ Gene goes on to share his background, which resonates with both software develop > Markdown/reStructuredText, and looking for opportunities to make that > workflow better." -Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. +Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, a less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand. We are living through change management in our content management. -He goes on to ask, with double-spaces after periods, which I find absolutely endearing, +He goes on to ask, with double-spaces after periods, which I find endearing, > "I still have companies asking about using a wiki for documentation when > considering jettisoning their legacy documentation tools, which aren't @@ -52,17 +52,17 @@ He goes on to ask, with double-spaces after periods, which I find absolutely end > "What are your thoughts on the differences between using a wiki and using > Git/Markdown, that I might be able to give them more substantive arguments?" -This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgement on either method. +This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgment on either method. -If I were in his shoes, I'd be curious and asking questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course informs your requirements list and considerations. +If I were in his shoes, I'd be curious and ask questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course, informs your requirements list and considerations. ## Consider the workflow - sit in another environment -For me, when moving towards a docs as code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. +For me, when moving towards a docs-as-code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory. ## Authentication and privacy needs -Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessible only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. +Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessed only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. (Updated July 2022: refer to [Changing the visibility of your GitHub Pages site](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) for information about managing access control for your project site by publishing the site publicly or privately on Enterprise Cloud GitHub.) You can implement an authentication workflow on a site uploaded to GitHub Pages, but you then need to have the web development resources to maintain the login requirement. You could use GitHub Enterprise Pages with GitHub Enterprise requiring a VPN connection to view pages. Security and openness decisions may preclude one solution or another. diff --git a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md index 9bb5c8c6..1c37de56 100644 --- a/_posts/articles/2018-01-06-video-presentations-docs-like-code.md +++ b/_posts/articles/2018-01-06-video-presentations-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "In the last three years of Write the Docs conferences, you can learn f last_modified_at: Sat Jan 6 10:29:44 CST 2018 categories: articles author: anne_gentle -tags: [writethedocs, video, conferences, github, git, collaboration, transformation] +tags: [writethedocs, video, conferences, GitHub, git, collaboration, transformation] image: path: /images/wtd-eur-2017.jpg caption: "[Flickr writethedocs](https://flic.kr/p/LqxXHE)" diff --git a/_posts/articles/2018-02-12-change-case-study.md b/_posts/articles/2018-02-12-change-case-study.md index 6ad84c3e..769aed77 100644 --- a/_posts/articles/2018-02-12-change-case-study.md +++ b/_posts/articles/2018-02-12-change-case-study.md @@ -5,7 +5,7 @@ excerpt: Changing from a content management system to Jekyll and all the change last_modified_at: Mon Feb 12 09:06:03 CST 2018 categories: articles author: tom_johnson -tags: [engineering, security, github, git, jekyll, static site, change, culture, teamwork, collaboration, development] +tags: [engineering, security, GitHub, git, jekyll, static site, change, culture, teamwork, collaboration, development] image: path: /images/laurencehorten-traintracks.jpg caption: "[Flickr laurencehorton](https://flic.kr/p/e3AsFw)" diff --git a/_posts/articles/2018-04-16-practical-advice.md b/_posts/articles/2018-04-16-practical-advice.md index c6b3e9e1..5029fa64 100644 --- a/_posts/articles/2018-04-16-practical-advice.md +++ b/_posts/articles/2018-04-16-practical-advice.md @@ -5,7 +5,7 @@ excerpt: What does it take to publish a technical book using GitHub? Let's dig i last_modified_at: Fri Apr 20 21:01:44 CDT 2018 categories: articles author: anne_gentle -tags: [book, publishing, github, git, gitbook, lulu, self-publishing, collaboration, design, layout] +tags: [book, publishing, GitHub, git, gitbook, lulu, self-publishing, collaboration, design, layout] image: path: /images/designbyandren-lightbulb.jpg caption: "[Flickr designbyandren](https://flic.kr/p/cMiQAJ)" diff --git a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md index ed5fabd4..e686dd3a 100644 --- a/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md +++ b/_posts/articles/2020-11-06-ten-tips-maintaining-long-term-docs-like-code.md @@ -5,7 +5,7 @@ excerpt: "Learn about one team's journey to keep a long-term relationship with t last_modified_at: Fri Nov 6 20:47:45 CST 2020 categories: articles author: gary_niemen -tags: [cicd, backstage, spotify, github, git, portal, internal, documentation, developer, docs] +tags: [cicd, backstage, spotify, GitHub, git, portal, internal, documentation, developer, docs] image: path: /images/spotify/soundboard-han.ailes.jpg caption: "[Flickr han.ailes](https://flic.kr/p/oVPTVm)" diff --git a/articles/index.md b/articles/index.md index 6a41c6cb..236b9caa 100644 --- a/articles/index.md +++ b/articles/index.md @@ -5,6 +5,3 @@ excerpt: "Read articles to learn more about the docs like code vision and how to search: false entries_layout: grid --- - - -{% include sign-up.html %} From d3aeeb5ef9e91070bebf9d1b4e1c024e5d603bcc Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Tue, 12 Jul 2022 12:14:22 -0500 Subject: [PATCH 13/13] Update Gemfile --- Gemfile | 1 - Gemfile.lock | 1 - 2 files changed, 2 deletions(-) diff --git a/Gemfile b/Gemfile index 0d1ba16d..6193a032 100644 --- a/Gemfile +++ b/Gemfile @@ -2,4 +2,3 @@ source "https://rubygems.org" gem "jekyll-theme-so-simple" gem "html-proofer" -gem "jekyll-seo-tag" \ No newline at end of file diff --git a/Gemfile.lock b/Gemfile.lock index 1ac7e1ec..90987b46 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -128,7 +128,6 @@ PLATFORMS DEPENDENCIES html-proofer - jekyll-seo-tag jekyll-theme-so-simple BUNDLED WITH