update whats new

Author: tomjoht

_docs/introduction_to_rest_apis/whats_new.md

@@ -18,7 +18,10 @@ The following are the most recent updates to the API documentation course.
 
 ## January 2021
 
-* 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.
+* 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.

_docs/metrics_and_measurement/docapis_metrics_and_measurement.md

@@ -6,7 +6,7 @@ weight: 13.0
 sidebar: docapis
 section: metrics
 path1: docapis_metrics_and_measurement.html
-last-modified: 2021-02-06
+last-modified: 2022-02-07
 ---
 
 Metrics and measurement addresses ways to measure API documentation quality and how to track your progress on improvement. You can use the quality checklist here to review essential components of documentation and decide how your API docs measure up. The checklist can be a way to investigate, analyze, and interrogate your documentation from another perspective and discover ways to improve it.

_docs/metrics_and_measurement/docapis_metrics_assessing_information_quality.md

@@ -6,7 +6,7 @@ weight: 13.2
 sidebar: docapis
 section: metrics
 path1: docapis_metrics_and_measurement.html
-last-modified: 2022-01-31
+last-modified: 2022-02-07
 ---
 
 In the previous topic, [Measuring documentation quality through user feedback](permalink: 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.

_docs/metrics_and_measurement/docapis_metrics_measuring_impact.md

@@ -6,7 +6,7 @@ weight: 13.1
 sidebar: docapis
 section: metrics
 path1: docapis_metrics_and_measurement.html
-last-modified: 2022-01-31
+last-modified: 2022-02-07
 ---
 
 As you set goals for your role or team, you might want to measure your impact on documentation quality in some way. The main reason for measuring your impact should be to evaluate your progress against documentation improvement goals. If you don't have any data to provide feedback on your efforts, it's hard to know if you're making a difference.

_docs/metrics_and_measurement/docapis_quality_checklist.md

@@ -6,7 +6,7 @@ weight: 13.3
 sidebar: docapis
 section: metrics
 path1: docapis_metrics_and_measurement.html
-last-modified: 2022-01-31
+last-modified: 2022-02-07
 redirect_from:
 - /learnapidoc/docapis_metrics_second_level_checklist.html
 - /learnapidoc/docapis_metrics_first_level_checklist.html
@@ -19,7 +19,7 @@ As indicated earlier, my goal is to create a practical guide for measuring quali
 * TOC
 {:toc}  
 
-## API documentation quality checklist
+## API documentation quality checklist {#comprehensive_version}
 
 The following checklist is a checklist that involves a deep look at your docs. The checklist's criteria are in no particular order Also, the list shouldn't be seen as definitive or as a foolproof recipe for perfect documentation. Some points might apply more than others, depending on your product, domain, and audience. But overall, these are criteria/characteristics that will likely lead to a better experience with developer docs.
 
@@ -37,7 +37,7 @@ li.checkboxListType1 {
 {% assign cb-end = "</li>" %}
 
 <div style="background-color: #eef; padding: 15px; margin-top: 30px; margin-bottom: 30px;" markdown="block">
-<div style="margin-top: 20px; margin-bottom: 20px; font-size:24px; text-align: center;">API documentation quality checklist</div>
+<div style="margin-top: 20px; margin-bottom: 20px; font-size:24px; text-align: center;">API documentation quality checklist (comprehensive version)</div>
 
 ### Findability
 
@@ -95,7 +95,7 @@ li.checkboxListType1 {
 
 </div>
 
-For a version of this checklist that is easy to copy and paste, see [Quality checklist for API docs (simplified html)](docapis_quality_checklist_html.html). This output strips away most formatting and just list the various criteria in a basic HTML file. Copy and paste the content into Google Docs or Microsoft Word. Then as you go through the content, make your notes in the "Assessment" area.
+For a version of this checklist that is easy to copy and paste, see [Quality checklist for API docs (simplified html) -- comprehensive version](docapis_quality_checklist_html.html). This output strips away most formatting and just list the various criteria in a basic HTML file. Copy and paste the content into Google Docs or Microsoft Word. Then as you go through the content, make your notes in the "Assessment" area.
 
 {% include random_ad1.html %}
 
@@ -115,7 +115,85 @@ As you evaluate your docs, consider the following:
 
 * **Doc scope**:  If you're working on a developer portal, chances are you don't own the entire portal. You might just own one little section of the portal. That's okay. You can limit your review to just the scope that you own. Granted, the user journeys might extend beyond this scope, but start with your stewardship first. The last thing you want to do is start a war with other authors by identifying all kinds of issues with their content (at least not before you address your own issues first).
 * **Levels of assessment**: Another consideration is just how much you can assess without more familiarity with docs. You can't know if the steps are accurate unless you go through the steps. You can't know if the docs are consistent unless you've read all the documentation. You can't know if the code works unless you can run it in a test environment. It might take more than a year working with the docs to be able to make these kinds of assessments. So pick and choose the criteria that are appropriate for your level of familiarity with the docs.
+* **Good docs can't fix bad design**: Poor API design will make even good docs problematic, no matter how well-written your content is. If the API has inconsistent naming, incomplete parameters, doesn’t map to user journeys, and is cumbersome to use, then documentation also becomes more cumbersome to follow and implement. Good docs can't fix bad API design, though docs can try to salvage the user experience.
 
 {% include random_ad4.html %}
 
+## Short version of the API documentation quality checklist {#short_version}
+
+Feedback I've received about the checklist is that it's too long &mdash; isn't there a lightweight version? Based on this feedback, I selected what I think are the highest priority criteria in each section. But again, as I've said elsewhere, my selections here are somewhat arbitrary and might depend on your particular product, user, and domain.
+
+<div style="background-color: #eef; padding: 15px; margin-top: 30px; margin-bottom: 30px;" markdown="block">
+<div style="margin-top: 20px; margin-bottom: 20px; font-size:24px; text-align: center;">API documentation quality checklist (short version)</div>
+
+### Findability
+
+<ul class="checkLists">
+{% assign findabilityList = site.data.quality_checklist.findability %}
+{% for item in findabilityList %}
+{% if item.priority == "high" %}
+{{cb1}}<b>{{item.title}}.</b> {{item.description}} {{cb-end}}
+{% endif %}
+{% endfor %}
+</ul>
+
+### Accuracy
+
+<ul class="checkLists">
+{% assign accuracyList = site.data.quality_checklist.accuracy %}
+{% for item in accuracyList %}
+{% if item.priority == "high" %}
+{{cb1}}<b>{{item.title}}.</b> {{item.description}} {{cb-end}}
+{% endif %}
+{% endfor %}
+</ul>
+
+### Relevance
+
+<ul class="checkLists">
+{% assign relevanceList = site.data.quality_checklist.relevance %}
+{% for item in relevanceList %}
+{% if item.priority == "high" %}
+{{cb1}}<b>{{item.title}}.</b> {{item.description}} {{cb-end}}
+{% endif %}
+{% endfor %}
+</ul>
+
+### Clarity
+
+<ul class="checkLists">
+{% assign clarityList = site.data.quality_checklist.clarity %}
+{% for item in clarityList %}
+{% if item.priority == "high" %}
+{{cb1}}<b>{{item.title}}.</b> {{item.description}} {{cb-end}}
+{% endif %}
+{% endfor %}
+</ul>
+
+### Completeness
+
+<ul class="checkLists">
+{% assign completenessList = site.data.quality_checklist.completeness %}
+{% for item in completenessList %}
+{% if item.priority == "high" %}
+{{cb1}}<b>{{item.title}}.</b> {{item.description}} {{cb-end}}
+{% endif %}
+{% endfor %}
+</ul>
+
+### Readability
+
+<ul class="checkLists">
+{% assign readabilityList = site.data.quality_checklist.readability %}
+{% for item in readabilityList %}
+{% if item.priority == "high" %}
+{{cb1}}<b>{{item.title}}.</b> {{item.description}} {{cb-end}}
+{% endif %}
+{% endfor %}
+</ul>
+
+</div>
+
+For the copy/paste version of this checklist, see [Quality checklist for API docs (simplified html) --- short version](docapis_quality_checklist_html_short.html). Similar to the simplified form of the comprehensive version, this output strips away most formatting and just list the various criteria in a basic HTML file.
+
 {% include random_ad2.html %}

_docs/metrics_and_measurement/docapis_quality_checklist_html.html

@@ -18,7 +18,7 @@
 
 </style>
 
-<h1>API documentation quality assessment</h1>
+<h1>Quality checklist for API docs (simplified html) -- comprehensive version</h1>
 
 <h2 class="criteriaCategory">FINDABILITY</h2>
 {% assign findabilityList = site.data.quality_checklist.findability %}{% for item in findabilityList %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>

_docs/metrics_and_measurement/docapis_quality_checklist_html_short.html

@@ -0,0 +1,40 @@
+---
+layout: none
+progress: false
+permalink: docapis_quality_checklist_html_short.html
+---
+
+<style>
+p.criteriaDescription {
+  margin-left: 50px;
+  font-size: 12px;
+  font-style: italic;
+  color: darkgoldenrod;
+}
+
+h2.criteriaCategory {
+  color: maroon;
+}
+
+</style>
+
+<h1>Quality checklist for API docs (simplified html) -- short version</h1>
+
+<h2 class="criteriaCategory">FINDABILITY</h2>
+{% assign findabilityList = site.data.quality_checklist.findability %}{% for item in findabilityList %}{% if item.priority == "high" %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>
+{% endif %}{% endfor %}
+<h2 class="criteriaCategory">ACCURACY</h2>
+{% assign accuracyList = site.data.quality_checklist.accuracy %}{% for item in accuracyList %}{% if item.priority == "high" %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>
+{% endif %}{% endfor %}
+<h2 class="criteriaCategory">RELEVANCE</h2>
+{% assign relevanceList = site.data.quality_checklist.relevance %}{% for item in relevanceList %}{% if item.priority == "high" %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>
+{% endif %}{% endfor %}
+<h2 class="criteriaCategory">CLARITY</h2>
+{% assign clarityList = site.data.quality_checklist.clarity %}{% for item in clarityList %}{% if item.priority == "high" %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>
+{% endif %}{% endfor %}
+<h2 class="criteriaCategory">COMPLETENESS</h2>
+{% assign completenessList = site.data.quality_checklist.completeness %}{% for item in completenessList %}{% if item.priority == "high" %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>
+{% endif %}{% endfor %}
+<h2 class="criteriaCategory">READABILITY</h2>
+{% assign readabilityList = site.data.quality_checklist.readability %}{% for item in readabilityList %}{% if item.priority == "high" %}<h3>{{item.title}}</h3><p class="criteriaDescription">{{item.description | strip_html}}</p><p>Assessment:</p>
+{% endif %}{% endfor %}

_docs/metrics_and_measurement/docapis_quantifying_progress.md

@@ -22,15 +22,13 @@ And yet, to achieve the level of information quality, we didn't have to rely on
 
 {% include random_ad1.html %}
 
-Note that sometimes poor API design will make even good docs problematic, no matter how good your content is. If the API has inconsistent naming, incomplete parameters, doesn't map to user journeys, and is cumbersome to use, then documentation also becomes more cumbersome to follow and implement. Good docs can't fix bad API design, though docs can try to salvage the user experience. If you have to explain the equivalent of String Theory and Lagrange Multipliers in your docs, give yourself extra points even if clarity is still debatable.
-
 ## Moving towards quantification
 
-In my initial go-around with the quality checklist, I tried to move towards quanitification by including scores and weights for each criteria, and then dividing the achieved number of points by the total points. From this scoring, you can move from qualitative to quantitative measurement.
+In my initial go-around with the quality checklist, I tried to move towards quantification by including scores and weights for each criteria, and then dividing the achieved number of points by the total points. From this scoring, I tried to move from qualitative to quantitative measurement.
 
 {% include random_ad2.html %}
 
-However, in practice, I found that assigning scores for each section felt very arbitrary and subject to personal whims. I don't think others would find the score meaningful either. Instead, just having a checklist of criteria to consider was value enough. In later revisions to the content here, I stripped out the section on quantification because I want the advice I give here to be helpful in practice, not just theory.
+However, in practice, I found that assigning scores for each section felt arbitrary and subject to personal whims. I don't think others found the scores meaningful either. Instead, just having a checklist of criteria to consider was valuable enough. That's why i stripped out the section on quantification in later revisions to the content — because I want the advice I give here to be helpful in practice, not just theory.
 
 I'm not saying that some approach to quantifying documentation wouldn't work, just that my approach did not. Also, recognize that the quality checklist has no official data to support it — instead, these best practices come from experience in the industry and from best practices that I and others have observed within the realm of developer documentation.