Search results

  1. I'd Rather Be Writing
  2. Docs
  3. Chapter 17: Additional resources

What's wrong with this topic answer key

Last updated: Aug 29, 2019

Download PDF

This is the answer key for Activity: What’s wrong with this API reference topic.

After you’ve finished commenting on the Google Doc, go to this annotated Google doc.

Annotated Google doc showing answers

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 letting me know. You can also add your own comments on the Google Doc answer key.

Answer key:

Resource description:

  • wordy. should be more concise and action-oriented
  • Surfreport probably shouldn’t capitalized

Endpoints and definition:

  • GET/POST should just be GET

  • no need for colon in {:beachId}

  • consider color coding {beachId}

Parameters:

  • Query string parameters are mixed into same table as Path parameters. Separate into different tables.

  • Where you get the beach ID isn’t specified

  • Number versus Integer is potentially inconsistent. Technically, a number refers to a float or double (which would allow for decimals), while an integer refers to a whole number. In this case, I doubt the beach IDs have decimals.

  • No default specified for time parameter

  • With time data types, why do some data types have examples but not all?

Sample request:

  • not in curl format

  • only one query string parameter shown; should include time too

  • zip query string parameter is included but not defined anywhere

  • appID includes long API key that should likely be shortened to a variable such as APIKEY

Sample response:

  • includes riptide element that isn’t defined in response definition

  • riptide missing comma after second instance

  • riptide not shown in third hour block

  • indentation formatting is a bit messed up with word riptide

Response definition:

  • wind description doesn’t indicate what measurement is used (knots?)

  • for wind, “int” should be spelled out as integer

  • watertemp doesn’t indicate measurement units either

  • surfheight data type is “Map” when it should be Integer

  • recommendation doesn’t include more detail such as how many possible recommendation strings are available, and what they even mean.

  • surfheight should either be surf_height or surfheight – response example conflicts with usage in response definition table

  • no hierarchy expressed for child elements (e.g., tide, wind, watertemp)

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

154% Complete

154/166 pages complete. Only 12 more pages to go.

« Previous: Chapter 17: Glossary

© 2024 Tom Johnson