Skip to content

Commit 3294125

Browse files
tomjohttomjoht
committed
fine tuning ebook content
1 parent da099ac commit 3294125

File tree

61 files changed

+195
-4170
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+195
-4170
lines changed

‎.gitignore

+3-3
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@ _site/
33
.jekyll-metadata
44
**/.DS_Store
55
pdf/docapis.pdf
6-
/mobi/
6+
/ebooks/
77
*.mobi
88
*.zip
99
*.pdf
1010
*.epub
11-
mobi/docapis.mobi
12-
mobi/docapis.epub
11+
ebooks/docapis.mobi
12+
ebooks/docapis.epub
1313
reindex.sh
1414
images

‎Gemfile.lock

+16-13
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
GEM
22
remote: https://rubygems.org/
33
specs:
4-
activesupport (6.0.4.1)
4+
activesupport (6.0.4.4)
55
concurrent-ruby (~> 1.0, >= 1.0.2)
66
i18n (>= 0.7, < 2)
77
minitest (~> 5.1)
@@ -25,10 +25,10 @@ GEM
2525
concurrent-ruby (1.1.9)
2626
dnsruby (1.61.7)
2727
simpleidn (~> 0.1)
28-
em-websocket (0.5.2)
28+
em-websocket (0.5.3)
2929
eventmachine (>= 0.12.9)
30-
http_parser.rb (~> 0.6.0)
31-
ethon (0.14.0)
30+
http_parser.rb (~> 0)
31+
ethon (0.15.0)
3232
ffi (>= 1.15.0)
3333
eventmachine (1.2.7)
3434
execjs (2.8.1)
@@ -55,8 +55,8 @@ GEM
5555
filesize (0.2.0)
5656
forwardable-extended (2.6.0)
5757
gemoji (3.0.1)
58-
github-pages (219)
59-
github-pages-health-check (= 1.17.7)
58+
github-pages (223)
59+
github-pages-health-check (= 1.17.9)
6060
jekyll (= 3.9.0)
6161
jekyll-avatar (= 0.7.0)
6262
jekyll-coffeescript (= 1.1.1)
@@ -65,6 +65,7 @@ GEM
6565
jekyll-feed (= 0.15.1)
6666
jekyll-gist (= 1.5.0)
6767
jekyll-github-metadata (= 2.13.0)
68+
jekyll-include-cache (= 0.2.1)
6869
jekyll-mentions (= 1.6.0)
6970
jekyll-optional-front-matter (= 0.3.2)
7071
jekyll-paginate (= 1.1.0)
@@ -96,10 +97,10 @@ GEM
9697
liquid (= 4.0.3)
9798
mercenary (~> 0.3)
9899
minima (= 2.5.1)
99-
nokogiri (>= 1.10.4, < 2.0)
100+
nokogiri (>= 1.12.5, < 2.0)
100101
rouge (= 3.26.0)
101102
terminal-table (~> 1.4)
102-
github-pages-health-check (1.17.7)
103+
github-pages-health-check (1.17.9)
103104
addressable (~> 2.3)
104105
dnsruby (~> 1.60)
105106
octokit (~> 4.0)
@@ -108,7 +109,7 @@ GEM
108109
html-pipeline (2.14.0)
109110
activesupport (>= 2)
110111
nokogiri (>= 1.4)
111-
http_parser.rb (0.6.0)
112+
http_parser.rb (0.8.0)
112113
httpclient (2.8.3)
113114
i18n (0.9.5)
114115
concurrent-ruby (~> 1.0)
@@ -155,6 +156,8 @@ GEM
155156
jekyll-github-metadata (2.13.0)
156157
jekyll (>= 3.4, < 5.0)
157158
octokit (~> 4.0, != 4.4.0)
159+
jekyll-include-cache (0.2.1)
160+
jekyll (>= 3.7, < 5.0)
158161
jekyll-last-modified-at (1.3.0)
159162
jekyll (>= 3.7, < 5.0)
160163
posix-spawn (~> 0.3.9)
@@ -230,7 +233,7 @@ GEM
230233
gemoji (~> 3.0)
231234
html-pipeline (~> 2.2)
232235
jekyll (>= 3.0, < 5.0)
233-
json (2.5.1)
236+
json (2.6.1)
234237
kramdown (2.3.1)
235238
rexml
236239
kramdown-parser-gfm (1.1.0)
@@ -245,7 +248,7 @@ GEM
245248
jekyll (>= 3.5, < 5.0)
246249
jekyll-feed (~> 0.9)
247250
jekyll-seo-tag (~> 2.1)
248-
minitest (5.14.4)
251+
minitest (5.15.0)
249252
multipart-post (2.1.1)
250253
nokogiri (1.12.5)
251254
mini_portile2 (~> 2.6.1)
@@ -258,7 +261,7 @@ GEM
258261
posix-spawn (0.3.15)
259262
progressbar (1.11.0)
260263
public_suffix (4.0.6)
261-
racc (1.5.2)
264+
racc (1.6.0)
262265
rb-fsevent (0.11.0)
263266
rb-inotify (0.10.1)
264267
ffi (~> 1.0)
@@ -291,7 +294,7 @@ GEM
291294
unf_ext (0.0.8)
292295
unicode-display_width (1.8.0)
293296
verbal_expressions (0.1.5)
294-
zeitwerk (2.4.2)
297+
zeitwerk (2.5.3)
295298

296299
PLATFORMS
297300
ruby

‎_config.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
title: Documenting REST APIs
2-
media: https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api
1+
title: Documenting APIs
2+
description: A guide for technical writers and engineers documenting APIs
33
language: english
44
sidebar: docapis
55

@@ -11,7 +11,7 @@ destination: _site
1111
port: 4000
1212
highlighter: rouge
1313
exclude:
14-
- mobi
14+
- ebooks
1515
- pdf
1616
format: web
1717

‎_config_kindle.yml

+18-3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
########## eBook tags (for docapis.opf) ###############
2+
# see the docapis.opf file for more details
3+
title: Documenting APIs
4+
description: A guide for technical writers and engineers documenting APIs
5+
author: Tom Johnson
6+
publisher: idratherbewriting.com
7+
isbn: 000000000000000
8+
subject: Technology & Engineering
9+
media: https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/api
10+
cover_image: restapi_kindletitle2.png
11+
112
language: english
213
media: images
314
format: kindle
@@ -7,12 +18,11 @@ destination: _site
718
port: 5000
819
highlighter: rouge
920
exclude:
10-
- mobi
21+
- ebooks
1122
- pdf
1223
- slides
1324
- images/comics/
14-
- serve_kindle.sh
15-
- build_kindle.sh
25+
- build_ebooks.sh
1626
- upload.sh
1727
- upload_outputs.sh
1828
- move.sh
@@ -22,6 +32,11 @@ exclude:
2232
- thank-you-for-donating.html
2333
- contact.html
2434
- aws_cli_notes.txt
35+
- image_purge_output.sh
36+
- image_purge_source.sh
37+
- instructions.md
38+
- assets/files
39+
- assets/js
2540

2641
markdown: kramdown
2742
kramdown:

‎_config_pdf.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ destination: _site
1515
port: 4000
1616
highlighter: rouge
1717
exclude:
18-
- mobi
18+
- ebooks
1919
- pdf
2020

2121
markdown: kramdown

‎_data/docapis.yml

+8-8
Original file line numberDiff line numberDiff line change
@@ -157,28 +157,28 @@ folders:
157157
- title: "Working in YAML"
158158
jurl: /pubapis_yaml.html
159159

160-
- title: "Step 1: The openapi object (OpenAPI tutorial)"
160+
- title: "Step 1: The openapi object"
161161
jurl: /pubapis_openapi_step1_openapi_object.html
162162

163-
- title: "Step 2: The info object (OpenAPI tutorial)"
163+
- title: "Step 2: The info object"
164164
jurl: /pubapis_openapi_step2_info_object.html
165165

166-
- title: "Step 3: The servers object (OpenAPI tutorial)"
166+
- title: "Step 3: The servers object"
167167
jurl: /pubapis_openapi_step3_servers_object.html
168168

169-
- title: "Step 4: The paths object (OpenAPI tutorial)"
169+
- title: "Step 4: The paths object"
170170
jurl: /pubapis_openapi_step4_paths_object.html
171171

172-
- title: "Step 5: The components object (OpenAPI tutorial)"
172+
- title: "Step 5: The components object"
173173
jurl: /pubapis_openapi_step5_components_object.html
174174

175-
- title: "Step 6: security object (OpenAPI tutorial)"
175+
- title: "Step 6: security object"
176176
jurl: /pubapis_openapi_step6_security_object.html
177177

178-
- title: "Step 7: The tags object (OpenAPI tutorial)"
178+
- title: "Step 7: The tags object"
179179
jurl: /pubapis_openapi_step7_tags_object.html
180180

181-
- title: "Step 8: The externalDocs object (OpenAPI tutorial)"
181+
- title: "Step 8: The externalDocs object"
182182
jurl: /pubapis_openapi_step8_externaldocs_object.html
183183

184184
- title: "Activity: Create an OpenAPI specification document"

‎_docs/additional_resources/api_doc_presentations.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ The following are other video recordings for API-related presentations.
1515
{:toc}
1616

1717
{% if site.format == "kindle" or site.format == "pdf" %}
18-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_course_videos.html] to view the content.*
18+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_course_videos.html] to view the content.*
1919
{% endif %}
2020

2121
{% if site.format == "web" %}

‎_docs/additional_resources/denver_workshop_recordings.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ These videos are from an API documentation workshop that I gave in Denver, Color
1515
{:toc}
1616

1717
{% if site.format == "kindle" or site.format == "pdf" %}
18-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_course_videos.html] to view the content.*
18+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_course_videos.html] to view the content.*
1919
{% endif %}
2020

2121
{% if site.format == "web" %}
2222

23-
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](docapis_workshop_videos.html)." %}
23+
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](docapis_course_videos.html)." %}
2424

2525
### Part I of III
2626

‎_docs/additional_resources/docapis_graphql.md

+10-3
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,15 @@ Here are some indicators of growth I found:
4949

5050
And, take a look at Google Trends:
5151

52+
{% if site.format == "kindle" or site.format == "pdf" %}
53+
*Note: This content doesn't embed well in print because it contains JavaScript. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
54+
{% endif %}
55+
56+
{% if site.format == "web" %}
5257
<script type="text/javascript" src="https://ssl.gstatic.com/trends_nrtr/1845_RC02/embed_loader.js"></script> <script type="text/javascript"> trends.embed.renderExploreWidget("TIMESERIES", {"comparisonItem":[{"keyword":"graphql","geo":"US","time":"today 5-y"}],"category":0,"property":""}, {"exploreQuery":"date=today%205-y&geo=US&q=graphql","guestPath":"https://trends.google.com:443/trends/embed/"}); </script>
5358

59+
{% endif %}
60+
5461
{% include random_ad2.html %}
5562

5663
## What is GraphQL?
@@ -98,7 +105,7 @@ The GraphQL foundation claims that their unique approach allows developers to de
98105
Furthermore, [Howtographql.com](https://www.howtographql.com/basics/1-graphql-is-the-better-rest/) claims that "REST APIs have shown to be too inflexible to keep up with the rapidly changing requirements of the clients that access them (and ...) GraphQL (…) solves many of the shortcomings and inefficiencies that developers experience when interacting with REST APIs." That same tutorial site features a video showing examples of these points:
99106

100107
{% if site.format == "kindle" or site.format == "pdf" %}
101-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
108+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
102109
{% endif %}
103110

104111
{% if site.format == "web" %}
@@ -156,7 +163,7 @@ This leads to Chris’s conclusion that tech writers are still needed here if on
156163
James Scott, another technical writer, also sees a role for technical writers in the world of GraphQL. You can see his concise and very helpful talk here:
157164

158165
{% if site.format == "kindle" or site.format == "pdf" %}
159-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
166+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
160167
{% endif %}
161168

162169
{% if site.format == "web" %}
@@ -182,7 +189,7 @@ My guess is that maybe the movement is [driven by developers who decide to use i
182189
However, tech writers that work with it do exist! Here, for example, is a technical writer, Andrew Johnston, at Shopify talking about their process of documenting a GraphQL API at Shopify:
183190

184191
{% if site.format == "kindle" or site.format == "pdf" %}
185-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
192+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_graphql.html] to view the content.*
186193
{% endif %}
187194

188195
{% if site.format == "web" %}

‎_docs/additional_resources/jeopardy_answer_key.md

+8
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,12 @@ last-modified: 2019-03-31
1111

1212
The API Jeopardy questions are in the [Conclusion section of Workshop Activities](workshop.html#conclusion).
1313

14+
{% if site.format == "kindle" or site.format == "pdf" %}
15+
*Note: This content doesn't embed well in print because it contains JavaScript. Please go to [https://idratherbewriting.com/learnapidoc/jeopardy_answer_key.html] to view the content.*
16+
{% endif %}
17+
18+
{% if site.format == "web" %}
19+
1420
### Questions (jeopardy answer key)
1521

1622
{% for item in site.data.jeopardy.list %}
@@ -20,3 +26,5 @@ The API Jeopardy questions are in the [Conclusion section of Workshop Activities
2026
<p>{{item.question}}</p>
2127
</div>
2228
{% endfor %}
29+
30+
{% endif %}

‎_docs/additional_resources/menlo_park_workshop_recordings.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ I recorded this full-day API documentation in Menlo Park, California, on Novembe
1515
{:toc}
1616

1717
{% if site.format == "kindle" or site.format == "pdf" %}
18-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_course_videos.html] to view the content.*
18+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_course_videos.html] to view the content.*
1919
{% endif %}
2020

2121
{% if site.format == "web" %}
2222

23-
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](docapis_workshop_videos.html)." %}
23+
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](docapis_course_videos.html)." %}
2424

2525
{% comment %}{% include random_ad3.html %}{% endcomment %}
2626

‎_docs/additional_resources/whats_wrong_answer_key.md

+9
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,14 @@ After you've finished commenting on the Google Doc, go to this [annotated Google
1717

1818
Alternatively, expand the answers below to see how many issues you found. If you found additional issues beyond those noted here, feel free to [drop me an email](http://idratherbewriting.com/learnapidoc/contact.html){: .noCrossRef} letting me know. You can also add your own comments on the Google Doc answer key.
1919

20+
{% include note.html content="For the most recent workshop recording, see the [Video recordings of API doc workshops](docapis_course_videos.html)." %}
21+
22+
{% if site.format == "kindle" or site.format == "pdf" %}
23+
*Note: This content doesn't embed well in print because it contains JavaScript. Please go to [https://idratherbewriting.com/learnapidoc/docapis_whats_wrong_answer_key.html] to view the content.*
24+
{% endif %}
25+
26+
{% if site.format == "web" %}
27+
2028
<button class="btn btn-danger" type="button" data-toggle="collapse" data-target="#answerkey" aria-expanded="false" aria-controls="collapseExample">
2129
Answer key
2230
</button>
@@ -88,3 +96,4 @@ Answer key:
8896

8997
</div>
9098
</div>
99+
{% endif %}

‎_docs/code_tutorials/devx-usability-examples.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ Many of the same principles in [*Universal Principles of Design: 125 Ways to Enh
101101
I recently participated in a short interview about usability for a class on [Usability & User Experience](https://usability-ux.weebly.com/). The presentation doesn't cover all the details from above, but it does touch upon usability in different scenarios (e.g., professional writing versus a blog, academic contexts, and other). [Kirk St.Amant](https://www.linkedin.com/in/kirk-st-amant-614a272/), a distinguished professor in the tech comm field, conducted the interview with me. You can see his usability course online at [https://usability-ux.weebly.com/](https://usability-ux.weebly.com/). Here's the video:
102102

103103
{% if site.format == "kindle" or site.format == "pdf" %}
104-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/devx-usability-examples.html] to view the content.*
104+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/devx-usability-examples.html] to view the content.*
105105
{% endif %}
106106

107107
{% if site.format == "web" %}

‎_docs/code_tutorials/docapis_code_difficulty.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ Despite the difficulties of documenting code, this area of documentation shouldn
8181
Check out the following video clip from engineer Ruthie Ben Dor during a Write the Docs conference. Responding to the question, "What are the three most important elements of producing API documentation?" Ruthie emphasizes the need to include code samples.
8282

8383
{% if site.format == "kindle" or site.format == "pdf" %}
84-
*Note: This content doesn't embed well in print, as it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_code_difficulty.html] to view the content.*
84+
*Note: This content doesn't embed well in print because it contains YouTube videos. Please go to [https://idratherbewriting.com/learnapidoc/docapis_code_difficulty.html] to view the content.*
8585
{% endif %}
8686

8787
{% if site.format == "web" %}

‎_docs/conceptual_topics_in_api_docs/docapis_doc_getting_started_section.md

+8
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,12 @@ Postman is a REST API GUI client that we explored earlier in [Submit requests th
6666

6767
To see how these Run in Postman buttons work, click this button:
6868

69+
{% if site.format == "kindle" or site.format == "pdf" %}
70+
*Note: This content doesn't embed well in print because it contains JavaScript. Please go to [https://idratherbewriting.com/learnapidoc/docapis_doc_getting_started_section.html] to view the content.*
71+
{% endif %}
72+
73+
{% if site.format == "web" %}
74+
6975
<div class="postman-run-button" style="margin-top:15px; margin-bottom: 15px"
7076
data-postman-action="collection/fork"
7177
data-postman-var-1="3578416-16cf5af1-26e2-4c89-bb99-c6be4e510dcb"
@@ -80,6 +86,8 @@ data-postman-collection-url="entityId=3578416-16cf5af1-26e2-4c89-bb99-c6be4e510d
8086
}(window, document, "_pm", "PostmanRunObject", "https://run.pstmn.io/button.js"));
8187
</script>
8288

89+
{% endif %}
90+
8391
When prompted, click **Fork Collection**. You'll then be prompted to sign into Postman first (create an account if you don't have one). Then you'll see the Postman web interface like this:
8492

8593
<figure><a target="_blank" class="noExtIcon" href="https://www.postman.com/tomjoht/workspace/openweathermap-demo/request/3578416-84eb6497-c2f8-4d83-8922-a0330dd50694?ctx=code"><img class="docimage large" src="{{site.media}}/postmanlaunchhandler3.png" alt="Postman web interface" /></a><figcaption>Postman web interface</figcaption></figure>

0 commit comments

Comments
 (0)