search

tomjoht / learnapidoc

Repo for API doc book
157 stars 59 forks source link

Various comments on pages #24

Closed tomjoht closed 4 years ago

tomjoht commented 4 years ago

Submitted from a reader:

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_understand_curl.html

QUESTIONS:

  1. Under “Query strings and parameters”, would it be helpful to emphasize that the ampersand symbol separates, rather than concatenates, parameter-value pairs?

A description of the ampersand as a separator appears on the “Step 3: Parameters” page in Section III of your course, and such a description is consistent with RFC 6920, Section 3:

Query Parameters: A "tag=value" list of optional query parameters as are used with HTTP URLs [RFC2616] with a separator character '&' between each. For example, "foo=bar&baz=bat".

--> TJ: updated

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_curl_with_petstore.html

QUESTIONS:

  1. In step 2 under “Create a new pet”, would “integer” be better than “integer (whole number)”?

Some readers might view “integer (whole number)” as a suggestion that integers and whole numbers are the same. Granted, an ID is unlikely to be negative, so an alternative to “integer” might be “integer (a whole number in this case)” or something similar.

--> TJ: updated

  1. In step 5 under “Create a new pet”, would providing detail about idempotency for specific HTTP methods be helpful to the reader?

Including an abbreviated version of the table in RFC 7231, Section 8.1.3, might help clarify that the POST method is not considered idempotent:

Method Idempotent

GET yes
POST no
PUT yes
DELETE yes

(Please excuse the poor table formatting.)

--> TJ: updated. I believe I was incorrect in my content b/c I said that POST was indempotent here. I corrected that and expanded on the reference with the link you provided. Thanks!

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_access_json_values.html

NOTES:

  1. In step 1 under “Printing a JSON value to the page”, the instructions appear to repeat the instructions in step 5 on the previous page (page title: “Inspect the JSON from the response payload”). That is, both steps ask the user to insert the following code below “console.log(response);”:

var content = response.wind.speed; $("#windSpeed").append(content);

  1. In step 2 under “Printing a JSON value to the page”, the reader is asked to insert a line so that the page body looks like this:
<body>
<h1>Sample page</h1>
<div id="windSpeed">Wind speed: </div>
</body>

However, the HTML provided in step 6 on the previous page already has the following:

<body>
<h1>Sample Page</h1>
wind speed: <span id="windSpeed"></span>
</body>

--> TJ: updated

  1. In step 2 under “Printing a JSON value to the page”, the first HTML snippet includes a closing H2 tag rather than a closing H1 tag (<h1>Sample page</h2>).

--> TJ: updated

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_diving_into_dot_notation.html

QUESTIONS:

  1. Would it be worth explaining why different variable-naming strategies are used in the code samples on the page (examples: “OpenWeatherMap”, “sarahjson”, “wind_speed”)?

--> TJ: this is just an inconsistency on my part. i don't have a strategy for using camelcase versus lowercase versus underscores. i will try to be more consistent, though. thanks for calling this out.

  1. Under “Showing wind conditions on the page”, should the HTML example include the <!DOCTYPE html> tag and the tag—to be consistent with the HTML example shown under “Exercise with dot notation”?

--> TJ: Updated. wow, you have a really careful eye here to catch all of this. I'm impressed by your meticulousness.

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_api_reference_tutorial_overview.html

NOTES:

  1. Under “After the tutorial”, the gray note includes a link to Section IV, but the link text differs from the Section IV title; the link text is “OpenAPI specification and Swagger”, but the Section IV title is “OpenAPI spec and generated reference docs”.

--> TJ: Updated

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_doc_parameters.html

QUESTIONS:

  1. Under “Max and min values for parameters”, would it be worth mentioning that allowed values need not be specified for boolean parameters because the boolean type already restricts values to true and false?

--> TJ: Updated

  1. Under “Max and min values for parameters”, would it be worth mentioning that allowed values for string parameters can be specified using the enum type (to emphasize that values can be restricted in ways other than by specifying a max and/or min)?

-- TJ: Updated. good callouts here, by the way. these are valid use cases that I had totally omitted!

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_finished_doc_result.html

NOTES:

  1. Under “Next steps”, the first activity link (“Activity: Find an Open Source Project”) takes the reader to the first activity in Section IX rather than the first activity in Section III.

--> TJ: I don't see this issue. Maybe I fixed it previously.

  1. Under “Next steps”, the text for the second activity link (“Activity: Critique or create an API reference topic”) differs from the corresponding sidebar title (“Activity: Evaluate API reference docs for core elements”) and the activity page title (“Activity: Evaluate API reference docs”).

--> TJ: Updated

PAGE:

https://idratherbewriting.com/learnapidoc/docapis_find_open_source_project.html

NOTES:

  1. The title on the page is “Activity: Find an Open-Source Project”, whereas the corresponding sidebar title is “Activity: Find an Open Source Project” (that is, the title in the sidebar lacks a hyphen in the compound modifier; similarly for the link text at the bottom of the “Putting it all together” page in Section III).

--> TJ: Updated. I noticed I was inconsistent in other places in the course, so I updated those too.

Note also that the activity title appears in headline-style capitalization (both at the top of the activity page and in the sidebar), whereas the other page/section titles appear in sentence-style capitalization.

-- TJ: Updated

tomjoht commented 4 years ago

updated