uploads to whats new

Author: tomjoht

_docs/introduction_to_rest_apis/whats_new.md

@@ -16,70 +16,19 @@ If you're looking to see what's new in the API doc site/course, you can browse n
 
 The following are the most recent updates to the API documentation course.
 
-## October 2022
-
-* Updated the Stoplight tutorial: [Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification document](pubapis_openapis_quickstart_stoplight.html). With many UI and other changes, this tutorial needed a lot of updates. It should now be aligned with the latest Stoplight UI and functionality.
-
-## May 2022
-
-* [Blobr: An API portal that arranges your API's use cases as individual products](pubapis_blobr.html). With Blobr, you can create an API store to launch and grow an API business with different monetization models.
-
-## January 2022
-
-* Revised the content in the [Metrics and Measurements](docapis_metrics_and_measurement.html) section as follows:
-  * Consolidated the first-level checkliist and second-level checklist into a [single checklist](docapis_quality_checklist.html).
-  * Removed the approach for quantifying each criteria into a score and weighting that score with the criteria's importance. This approach was something I experimented with but ultimately found that it didn't work in practice.
-  * Added a [lightweight version of the checklist](docapis_quality_checklist.html#short_version) that includes only two criteria from each category.
-
-## December 2021
-* [PDF and eBook formats](docapis_formats.html). Created PDF, Kindle, and EPUB versions of the course that you can download.
-* [Broadcasting your meeting notes to influence a wider audience](docapis_meeting_notes.html). Explains how to broadcast your meeting notes as a tool for influencing other groups.
-
-## November 2021
-
-* [The writing process](writing_process.html). A new section that covers the process for researching, drafting, writing, editing, and publishing documentation. Includes these topics:
-  * [Overview of the writing process](docapis_writing_process_overview.html)
-  * [1. Planning](docapis_planning.html)
-  * [2. Information gathering](docapis_information_gathering.html)
-  * [3. Writing](docapis_writing.html)
-  * [4. Reviewing](docapis_reviewing.html)
-  * [5. Publishing](docapis_publishing.html)
 
-## October 2021
+## June 2023
 
-[Using Oxygen XML with docs-as-code workflows](pubapis_oxygenxml.html). Added a new article in the publishing tools section using Oxygen XML.
-* [Other resources section in course overview](index.html#other-resources). Updated the Course overview with a list of additional resources (books, courses, etc.).
-
-## August 2021
-
-* [Ensuring documentation coverage with each software release](docapis_release_process.html). Covers best practices for ensuring that each new feature in a release has adequate documentation coverage.
-
-
-## Auto-generated list of updated pages
+* Converted the PDF download into separate PDFs of individual chapters rather than a full-length PDF (which was more than 900 pages long). Downloads to the individual chapters are available with each section overview and in the [Download  PDFs](docapis_formats.html) page. 
+* Removed the Kindle and ePUB download options, as they weren't popular and the process created more complexity than it was worth.
 
 {% include random_ad4.html %}
 
-This list is auto-generated based on the last-modified timestamp on pages, scoped to the last 60 days. How does the script work? Every page has a "Last updated" line below the title. This script looks for any pages with a timestamp that appears within the last 60 days.
-
-{% assign timeframe = 5184000 %}
-{% assign count = 0 %}
-
-{% for post in site.docs %}
-  {% assign post_in_seconds = post.last-modified | date: "%s" | plus: 0 %}
-  {% assign recent_posts = "now" | date: "%s" | minus: timeframe  %}
-
-  {% if post_in_seconds > recent_posts %}
-  {% assign count = count | plus:1 %}
-
-* {{post.last-modified | date: "%b %d, %Y" }}: <a href="{{ post.permalink | remove: "/" }}">{{ post.title }}</a>
-{% if count == 15 %}{% break %}{% endif %}
-{% endif %}
-{% endfor %}
+## October 2022
 
-{% comment %}
-details about the script logic above: https://stackoverflow.com/questions/46672231/in-jekyll-how-to-show-posts-from-last-week
-{% endcomment %}
+* Updated the Stoplight tutorial: [Getting started tutorial: Using Stoplight Studio to create an OpenAPI specification document](pubapis_openapis_quickstart_stoplight.html). With many UI and other changes, this tutorial needed a lot of updates. It should now be aligned with the latest Stoplight UI and functionality.
 
+{% include random_ad1.html %}
 
 ## Seeing what content has been updated
 

_docs/metrics_and_measurement/docapis_metrics_assessing_information_quality.md

@@ -9,7 +9,7 @@ path1: docapis_metrics_and_measurement.html
 last-modified: 2022-02-07
 ---
 
-In the previous topic, [Measuring documentation quality through user feedback]( docapis_measuring_impact.html), I explained the challenges of getting feedback from user surveys as a way to measure documentation quality. In this section, I'll survey the landscape on criteria and rubrics for assessing documentation quality.
+In the previous topic, [Measuring documentation quality through user feedback](docapis_measuring_impact.html), I explained the challenges of getting feedback from user surveys as a way to measure documentation quality. In this section, I'll survey the landscape on criteria and rubrics for assessing documentation quality.
 
 * TOC
 {:toc}

_docs/metrics_and_measurement/docapis_quality_checklist.md

@@ -14,7 +14,7 @@ redirect_from:
 
 *This section continues from the previous page, [Different approaches for assessing information quality](docapis_metrics_assessing_information_quality.html).*
 
-As indicated earlier, my goal is to create a practical guide for measuring quality. Instead of looking at docs against a list of general, abstract criteria, I recommend another approach: assessing docs against a list of characteristics that, if fulfilled, should lead to a hiqh-quality user experience automatically. Each of the characteristics must be specific, actionable, and unambiguous in how it would be implemented in your docs. In this section, I'll present a comprehensive quality checklist for API docs and developer portals.
+As indicated earlier, my goal is to create a practical guide for measuring quality. Instead of looking at docs against a list of general, abstract criteria, I recommend another approach: assessing docs against a list of characteristics that, if fulfilled, should lead to a high-quality user experience automatically. Each of the characteristics must be specific, actionable, and unambiguous in how it would be implemented in your docs. In this section, I'll present a comprehensive quality checklist for API docs and developer portals.
 
 * TOC
 {:toc}  

_docs/openapi_spec_and_generated_ref_docs/pubapis_openapi_intro.md

@@ -90,7 +90,7 @@ Learning the OpenAPI spec and constructing the YAML or JSON code by hand the fir
 
 Before we dive into ways to manually create the OpenAPI specification document, it's worth noting some other approaches to the task, beyond choosing whether to use a visual editor or manually write the code. You can also choose to auto-generate the OpenAPI spec from annotations in your programming code. This developer-centric approach may make sense if you have a large number of APIs or if it's not practical for technical writers to create this documentation. In my [2020 Developer Documentation Trends survey](docapis_trends.html), approaches for auto-generating the spec versus manually generating it were split:
 
-<figure><a target="_blank" class="noExtIcon" href="https://idratherbewriting.com/learnapidoc/docapis_trends.html"><img class="docimage medium border" src="{{site.media}}/trends-generating-openapi.png" alt="Percentage of auto-generation versus manual creation"></a><figcaption>Percentage of auto-generation versus manual creation</figcaption></figure>
+<figure><a target="_blank" class="noExtIcon" href="docapis_trends.html"><img class="docimage medium border" src="{{site.media}}/trends-generating-openapi.png" alt="Percentage of auto-generation versus manual creation"></a><figcaption>Percentage of auto-generation versus manual creation</figcaption></figure>
 
 If you want to go the code-generation route, Swagger offers a variety of libraries that you can add to your programming code to generate the specification document. These Swagger libraries then parse the annotations that developers add and generate the OpenAPI specification document. These libraries are considered part of the ["Swagger Codegen"](https://swagger.io/swagger-codegen/) project. The annotation methods vary based on the programming language. For example, here's a [tutorial on annotating code with Swagger for Scalatra](http://www.infoq.com/articles/swagger-scalatra).
 

_sass/custom.scss

@@ -106,10 +106,11 @@ a[data="github"]:after {
   text-decoration: none;
   padding-left: 5px;
 }
-
+/*
 a[href*="idratherbewriting.com"]:after {
   content: "" !important;
 }
+*/
 
 a[href].noCrossRef::after, a[href].noExtIcon::after, pre a::after, pre.highlight a::after, pre.highlight code a::after, pre code a.vglnk::after,
 a.no_icon:after

assets/css/pdf/font-awesome.min.css

@@ -47,10 +47,21 @@ th  {color: white}
   margin-left:40px;
 }
 
-/* cross-references to pages */
+/* uncomment this style if you want page number cross refs to appear in parentheses
+after internal links. i commented this out because some internal links appear in 
+the chapter outputs, others don't.
+/*
+/* cross-references to pages 
 a[href]::after {
     content: " (p. " target-counter(attr(href), page) ")"
 }
+*/
+
+/*
+a[href]::after {
+    content: ""
+}
+*/
 
 /* uncomment this style if you want to include the href target in 
 parentheses after each link. I think this style significantly interferes with
@@ -71,19 +82,30 @@ a::after{
   }
 */
 
+a[href^="http://"]:not([href*="idratherbewriting.com/learnapidoc"]),
+a[href^="https://"]:not([href*="idratherbewriting.com/learnapidoc"])::after {
+  content: "";
+  display: inline-block;
+  width: 14px; /* Your icon width */
+  height: 12px; /* Your icon height */
+  margin-left: 1px; /* Space between the link and the icon */
+  background: url('/Users/tomjoht/projects/learnapidoc/images/externalIcon.svg') no-repeat center center; /* URL of your icon */
+  background-size: contain;
+}
 
 
-a[href] {
-    color: #337CD6 !important;
-    text-decoration: none;
+p > a[href] {
+    color: black !important;
+    text-decoration: underline;
+    text-decoration-color: lightgray;
 }
 
 /* this style makes it so that relative URLs are expected to appear in the PDF output and so
 Prince will retain the cross reference in parentheses afterwards, but for absolute URLs, there won't 
 be a cross reference in the parentheses afterwards, and likewise there won't appear any URL in 
 parentheses after the link, as that harms readability. */
 
-a[href*="mailto"]::after, a[data-toggle="tooltip"]::after, a[href].noCrossRef::after, a[href^="http://"]::after, a[href^="https://"]::after {
+a[href*="mailto"]::after, a[data-toggle="tooltip"]::after, a[href].noCrossRef::after {
     content: "";
 }
 

assets/css/pdf/printstyles.css

@@ -1,4 +1,9 @@
+# Equivalent function
+myvenv() {
+    source /Users/tomjoht/myvenv/bin/activate
+}
 myvenv
+
 aws s3 cp ~/projects/learnapidoc/pdf/docapis_one.pdf s3://learnapidoc-outputs --profile wasabi
 aws s3 cp ~/projects/learnapidoc/pdf/docapis_two.pdf s3://learnapidoc-outputs --profile wasabi
 aws s3 cp ~/projects/learnapidoc/pdf/docapis_three.pdf s3://learnapidoc-outputs --profile wasabi
@@ -14,4 +19,4 @@ aws s3 cp ~/projects/learnapidoc/pdf/docapis_twelve.pdf s3://learnapidoc-outputs
 aws s3 cp ~/projects/learnapidoc/pdf/docapis_thirteen.pdf s3://learnapidoc-outputs --profile wasabi
 aws s3 cp ~/projects/learnapidoc/pdf/docapis_fourteen.pdf s3://learnapidoc-outputs --profile wasabi
 aws s3 cp ~/projects/learnapidoc/pdf/docapis_fifteen.pdf s3://learnapidoc-outputs --profile wasabi
-echo 'done uploading'
+echo 'done uploading'