Merge pull request #246 from justwriteclick/build

annegentle · web-flow · commit 9fa6b5b95356 · 2024-07-11T23:13:36.000-05:00
Cover updates, remove mailer signup
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -88,9 +88,9 @@ GEM
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
     multipart-post (2.1.1)
-    nokogiri (1.14.3-x86_64-darwin)
+    nokogiri (1.15.6-x86_64-darwin)
       racc (~> 1.4)
-    nokogiri (1.14.3-x86_64-linux)
+    nokogiri (1.15.6-x86_64-linux)
       racc (~> 1.4)
     nokogumbo (2.0.5)
       nokogiri (~> 1.8, >= 1.8.4)
@@ -101,12 +101,13 @@ GEM
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (4.0.6)
-    racc (1.6.2)
+    racc (1.7.3)
     rainbow (3.0.0)
     rb-fsevent (0.11.0)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
+    rexml (3.2.8)
+      strscan (>= 3.0.9)
     rouge (3.26.1)
     ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
@@ -115,6 +116,7 @@ GEM
     sawyer (0.8.2)
       addressable (>= 2.3.5)
       faraday (> 0.8, < 2.0)
+    strscan (3.1.0)
     terminal-table (2.0.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     typhoeus (1.4.0)
diff --git a/_layouts/learn.html b/_layouts/learn.html
@@ -21,8 +21,6 @@ <h1>{{ page.title }}</h1>
        </div>
        {{ content }}
 
-       {% include sign-up.html %}
-
        </div>
      </div>
     {% include footer.html %}
diff --git a/_posts/articles/2016-09-17-github-for-docs.md b/_posts/articles/2016-09-17-github-for-docs.md
@@ -53,5 +53,3 @@ I hope I'm talking to people who care a lot about words. Let's start with some v
 These definitions can give you decision points to make about information architecture, so think about which deliverables you'll make, who should review and collaborate on those deliverables, and how you can automate publishing with the chunks of a repository or an organization as overarching collections.
 
 Take a look at [this article's source on GitHub](https://raw.githubusercontent.com/justwriteclick/docslikecode/master/_posts/articles/2016-09-17-github-for-docs.md) to get a sense of the "source" for a document. We'll look at the source aspects in a future article. To stay in touch, subscribe to get relevant emails in your inbox.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2016-09-18-github-collaborators.md b/_posts/articles/2016-09-18-github-collaborators.md
@@ -32,5 +32,3 @@ When you write with people beyond your immediate team, ensure that those contrib
 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.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2016-09-23-doc-issues-tracking.md b/_posts/articles/2016-09-23-doc-issues-tracking.md
@@ -40,5 +40,3 @@ 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 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
@@ -29,5 +29,3 @@ This video shows you how to clone a GitHub repo with an existing Jekyll theme an
 ### How it's made
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/{{ include.id }}" frameborder="0" allowfullscreen></iframe>
-
-{% 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
@@ -43,5 +43,3 @@ Here are some resources to get your first punch in that punch list:
 * Using Python Sphinx? The OpenStack docs theme has some Javascript you could re-use to pre-populate an Issue template so the reporter sends the page URL, the source URL, the git SHA of the commit for that version of the page, and the release version value. See this [docs.js snippet](https://github.com/openstack/openstackdocstheme/blob/master/openstackdocstheme/theme/openstackdocs/static/js/docs.js#L119).
 * 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
@@ -28,5 +28,3 @@ Here are some of the topics:
 * What about wikis?
 
 When you treat docs as code, what are your biggest barriers? Your looming concerns? Let me know so we can address these. Sign up below to learn more together.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-03-18-pantheon-case-study.md b/_posts/articles/2017-03-18-pantheon-case-study.md
@@ -66,5 +66,3 @@ As of March 2017, this workflow was not available to forks for security reasons.
 #### Are there any questions you wish you had asked before using GitHub for docs?
 
 How do the needs of open source software projects differ from those of a documentation project? Where does GitHub fail to fulfill the needs of documentation projects and how can those gaps be filled?
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-03-25-symantec-case-study.md b/_posts/articles/2017-03-25-symantec-case-study.md
@@ -127,5 +127,3 @@ The biggest thing we didn't do was integrate the Javadoc build completely into t
 On the other hand, because other doc components besides the Javadoc could only be built manually, more automation could have solved only part of the problem of keeping content up-to-date on the server. Ultimately, the decision not to automate the Javadoc made sense &mdash; there are always pain points on either side of a decision like this.
 
 We also didn't realize initially that we'd have to coordinate our doxygen build, which ran over only a small subset of the code, with multiple other doxygen builds over other parts of the code tree. I wound up working with lead devs on other coding projects to coordinate main page markup and config values so that we could all get the doc builds that we needed. This work was a bit fiddly, and produced an extra round of review with every Javadoc build to make sure that the right components were all properly included.
-
-{% include sign-up.html %}
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
@@ -94,5 +94,3 @@ Hugo looks for two pieces of front matter. The first is the presence of a parame
 If the `include` parameter isn't present, Hugo just uses the Markdown content in the file without copying content from elsewhere. This allows us to mix and match docs that are unique to one product with docs that share functionality with multiple products.
 
 It took some effort to get it set up, but now we don't even think about it. It's really easy for the content writers, and we'll be able to extend it when we add yet more versions in the future (we already are, in fact).
-
-{% include sign-up.html %}
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
@@ -67,5 +67,3 @@ 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. 
-
-{% 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
@@ -120,5 +120,3 @@ So, what did we learn from these challenges? I think the most important thing is
 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.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-06-03-api-docs-with-code.md b/_posts/articles/2017-06-03-api-docs-with-code.md
@@ -161,5 +161,3 @@ Each time that the code builds, the `swagger.json` file updates with the most cu
 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.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-06-05-free-open-source-api-doc-tools.md b/_posts/articles/2017-06-05-free-open-source-api-doc-tools.md
@@ -12,8 +12,6 @@ image:
 comments: true
 share: true
 ---
-{% include sign-up.html %}
-
 Open source API documentation generators
 ========================================
 
@@ -298,5 +296,3 @@ An **Application Programming Interface (API)** is a set of clearly defined metho
 -   **API providers**: To provide an overview of free and open source tools for companies that want to share, update or customize their API docs or developer portal.
 -   **Developer portal builders**: To provide an independent review of existing developer portal solutions that developer teams tasked with building developer portals can use as a reference in discussions with their clients, to make it easier to select the one that best fits their needs.
 -   **Technical writers**: To create a resource that tech writers can use to select the API documentation infrastructure that fits best with their existing authoring workflows.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-08-19-when-to-wiki.md b/_posts/articles/2017-08-19-when-to-wiki.md
@@ -93,5 +93,3 @@ Wikis may have a reputation built up over time with a lack of discipline in edit
 ## Bringing it home
 
 Even as I wrote back to Gene to answer his questions, and even as I incorporated the answers into the _Docs Like Code_ book, I continue to be challenged with my answers and to reconsider some of them. Tools come and go, and our ability as professional writers remains and shines: provide the best critical analysis of the content management tools, and then write and manage the heck out of the content and the talent that creates and maintains it.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-09-19-cisco-devnet-pubhub.md b/_posts/articles/2017-09-19-cisco-devnet-pubhub.md
@@ -67,5 +67,3 @@ Because the system is meant for individual teams to review their own content, th
 ## Do you have automation? If so, what type or tooling, and where is the automation in the workflow?
 
 Yes, absolutely as that's one of the drivers for the system, is to enable automation and integration into existing CI/CD workflows to keep in sync with code changes. The PubHub system uses Apache Kafka to manage notifications on updates for each repo and then publish them as static files. The automation for publishing is triggered when the team makes a "release" of the repository, indicating that the content is ready for public consumption.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2017-11-12-rackspace-case-study.md b/_posts/articles/2017-11-12-rackspace-case-study.md
@@ -106,5 +106,3 @@ Finally, another great resource is Anne Gentle’s [Docs like Code project](http
 Are you treating docs like code, or thinking about transforming your documentation processes? We’d love to hear your thoughts and experiences. If you have questions or want to know more about contributing to Rackspace documentation, see our [Quickstart](https://docs.rackspace.com/docs/style-guide/quickstart) or e-mail us at devdoc@rackspace.com.
 
 Originally published November 11, 2016, on the [Rackspace Blog](https://blog.rackspace.com/transforming-developer-and-support-documentation-with-docs-like-code).
-
-{% include sign-up.html %}
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
@@ -47,5 +47,3 @@ Even when I don't make it to the conference in person, the video recordings are
 {% include youtube.html id=page.youtubeIdRiona %}
 
 All this to say, the docs-like-code concepts are widely practiced in our industry, and each conference provides more inspiring examples. Perhaps you can watch these presentations and be inspired to integrate code and doc techniques.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2018-02-12-change-case-study.md b/_posts/articles/2018-02-12-change-case-study.md
@@ -248,5 +248,3 @@ To read some other docs-as-code posts on my blog, see the following:
 {: .tip}
 To Learn more about docs as code, see Anne Gentle's book [Docs Like Code](https://www.amazon.com/Docs-Like-Code-Anne-Gentle/dp/1365816079/ref=sr_1_1?ie=UTF8&qid=1508090523&sr=8-1&keywords=docs+like+code).
 
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2018-04-16-practical-advice.md b/_posts/articles/2018-04-16-practical-advice.md
@@ -87,5 +87,3 @@ I calculated the starting costs for six or five months, when I needed a monthly
 | **Total startup costs**    |  **$828**           |
 
 Based on Lulu reporting, I see the book brought in about $2500 in 12 months of the first and second edition being available. So while the startup costs are not nothing, I did see a profit from the effort. Really, though, the effort is paid off in helping others see the benefits I've observed and in sharing and learning. Let me know what you think about this method, the tools, and of course, the resulting book, *Docs Like Code*.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2018-06-05-cloudify-dont-stop-dreaming.md b/_posts/articles/2018-06-05-cloudify-dont-stop-dreaming.md
@@ -91,5 +91,3 @@ As much as I faced lots of frustration during the process, I learned a tremendou
 
 I hope that others can learn from the process we went through to see that it is both fun and productive to go for your dreams!
 
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2018-10-12-platformos-1of4.md b/_posts/articles/2018-10-12-platformos-1of4.md
@@ -110,5 +110,3 @@ This concluded our Information Architecture phase. We have discovered and organi
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
 _This article was originally written for the [platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-1-information-architecture)._
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2018-11-01-platformos-2of4.md b/_posts/articles/2018-11-01-platformos-2of4.md
@@ -143,5 +143,3 @@ We hope you enjoyed learning about how we started content production, how we bui
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
 _This article was originally written for the [platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2018-11-25-platformos-3of4.md b/_posts/articles/2018-11-25-platformos-3of4.md
@@ -113,5 +113,3 @@ Now that you’ve seen how we discovered the needs of our target audience, plann
 _We involved [UX Strategist Katalin Nagygyörgy](https://www.linkedin.com/in/nagygyorgykatalin/) in our process from the start. Through our collaboration, we could extract and collect all the necessary information using tried and true research methodologies and UX best practices._
 
 _This article was originally written for the [platformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-3-community)._
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2019-04-20-github-pages-python-sphinx.md b/_posts/articles/2019-04-20-github-pages-python-sphinx.md
@@ -88,5 +88,3 @@ Now you can run `make github` from the doc source directory to generate a local
 ## Pull it all together
 
 I've been working on a talk titled, "Make an Instant Web Site with Webhooks" for DevNet Create. In it, I show how to publish and host on GitHub Pages, which is built to use Jekyll by default, using Python Sphinx instead. I've got a GitHub repository set up at [annegentle/create-demo](https://github.com/annegentle/create-demo) as a demonstration. I'll post the slides when it's done. In the meantime, we'd love to see you next week! Visit the [DevNet Create site](https://developer.cisco.com/devnetcreate/2019) for more information.
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2020-02-26-platformos-4of4.md b/_posts/articles/2020-02-26-platformos-4of4.md
@@ -258,7 +258,5 @@ We’ve come a long way but there’s still a lot we can improve. Stay tuned, be
 
 _This article was co-authored by Pawel Kowalski, Front-End Developer and Performance Advocate at platformOS, and was originally written for the [PlatformOS Blog](https://www.platformos.com/blog/post/building-our-documentation-site-on-platformos-part-2-content-production-and-layouts)._
 
-{% include sign-up.html %}
-
 
 
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
@@ -139,5 +139,3 @@ One last note to let you know that **we have now open sourced TechDocs**. Let’
 * [Backstage](https://backstage.io), an open platform for building developer portals
 * [github.com/backstage](https://github.com/backstage/backstage)
 * [DevRelCon London, December 2019: Gary Niemen, The Hero’s Journey: How we are solving internal technical documentation at Spotify](https://www.linkedin.com/posts/garyniemen_how-we-are-solving-internal-technical-documentation-activity-6646078605594030080-4L31)
-
-{% include sign-up.html %}
diff --git a/_posts/articles/2021-01-09-survey-results-docs-like-code.md b/_posts/articles/2021-01-09-survey-results-docs-like-code.md
@@ -92,5 +92,3 @@ Also, engineers won't write unless they're told to. You need a push down from le
 > "Sarah Parson’s Write the Docs presentation on static site generators and Tom Johnson’s explanation of his Documentation Jekyll theme."
 
 This is not a section simply to point to the [Docs Like Code book](https://docslikecode.com/book/) as a resource, rather, it's to show that having additional resources including people you can ask questions is super valuable when learning how to treat docs like code. I'm grateful to the Write the Docs community and people who are also writing their experiences here and on other sites so we can all learn together. Thanks to everyone who shared their experiences and hard-earned wisdom!
-
-{% include sign-up.html %}
diff --git a/about/index.md b/about/index.md
@@ -31,5 +31,3 @@ In the [Learn section of the site](https://docslikecode.com/learn/), there are t
 Choose your adventure and start one of these sites - and learn how to do docs as code along the journey.
 
 ## Ready to learn more?
-
-{% include sign-up.html %}
diff --git a/images/docs-like-code-book.jpg b/images/docs-like-code-book.jpg
diff --git a/index.html b/index.html
@@ -58,5 +58,3 @@ <h2>Read the articles</h2>
 using GitHub for documentation. Let's find out the best practices and create a balance point between artisanal craft and automation efficiency.
 </p>
 </div>
-
-{% include sign-up.html %}
diff --git a/search/index.md b/search/index.md
@@ -7,5 +7,3 @@ search: false
 sitemap: false
 ---
 
-
-{% include sign-up.html %}
