Sorry, page not found. Try searching for the topic instead. Also, please let me know about the broken link.
11 |
--------------------------------------------------------------------------------
/Gemfile:
--------------------------------------------------------------------------------
1 | source 'https://rubygems.org'
2 |
3 | gem 'jekyll'
4 | gem 'webrick'
5 |
6 | group :jekyll_plugins do
7 | gem 'github-pages'
8 | gem 'jekyll-algolia'
9 | gem 'jekyll-redirect-from'
10 | gem 'jekyll-seo'
11 | gem 'jekyll-seo-tag'
12 | end
13 |
--------------------------------------------------------------------------------
/META-INF/container.xml:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | This repo is now inactive. I moved the content into [tomjoht.github.io repo](https://github.com/tomjoht/tomjoht.github.io), which surfaces the content at [idratherbewriting.com](https://idratherbewriting.com).
2 |
3 | The content is an API documentation course geared towards technical writers and engineers.
4 |
--------------------------------------------------------------------------------
/_config_simplifying_complexity.yml:
--------------------------------------------------------------------------------
1 | title: Simplifying Complexity
2 | description: A series of essays on how to simplify complex concepts and information for the purposes of software documentation.
3 | isbn: 000000000000000
4 | cover_image: ebook_cover.png
5 |
6 | sidebar: simplifying_complexity
7 |
--------------------------------------------------------------------------------
/_config_writing_process.yml:
--------------------------------------------------------------------------------
1 | title: The Writing Process
2 | description: A guide through the process for developing documentation content
3 | isbn: 000000000000000
4 | cover_image: ebook_cover.png
5 |
6 | sidebar: docapis
7 |
--------------------------------------------------------------------------------
/_data/topnav.yml:
--------------------------------------------------------------------------------
1 | ## Topnav single links
2 | ## if you want to list an external url, use external_url instead of url. the theme will apply a different link base.
3 |
4 | navbar_singleitems:
5 | - items:
6 | - title: Blog
7 | url: https://idratherbewriting.com
8 | - title: About
9 | url: docapis_about_the_author.html
10 | - title: Contact
11 | url: contact.html
12 | - title: Newsletter
13 | url: newsletter.html
14 | - title: Download PDFs
15 | url: docapis_formats.html
16 | topnav_dropdowns:
17 | - title: Topnav dropdowns
18 | folders:
19 | - title: GitHub
20 | folderitems:
21 | - title: GitHub repo
22 | url: https://github.com/tomjoht/learnapidoc/
23 | github_icon: show
24 | - title: Log an issue
25 | url: https://github.com/tomjoht/learnapidoc/issues/new
26 | github_icon: show
27 | - title: Closed issues
28 | url: https://github.com/tomjoht/learnapidoc/issues?q=is%3Aissue+is%3Aclosed
29 | github_icon: show
30 |
--------------------------------------------------------------------------------
/_data/writing_process.yml:
--------------------------------------------------------------------------------
1 | sidebartitle: The Writing Process
2 | folders:
3 |
4 | - title: "The writing process"
5 | jurl: /writing_process.html
6 | folderitems:
7 |
8 | - title: "Overview of the writing process"
9 | jurl: /docapis_writing_process_overview.html
10 |
11 | - title: "1. Planning"
12 | jurl: /docapis_planning.html
13 |
14 | - title: "2. Information gathering"
15 | jurl: /docapis_information_gathering.html
16 |
17 | - title: "3. Writing"
18 | jurl: /docapis_writing.html
19 |
20 | - title: "4. Reviewing"
21 | jurl: /docapis_reviewing.html
22 |
23 | - title: "5. Publishing"
24 | jurl: /docapis_publishing.html
25 |
26 | related_resources_title: Related resources
27 | related_resources_list:
28 | - title: "Documenting APIs"
29 | jurl: /learnapidoc/
30 |
31 | - title: "Some url"
32 | jurl: https://examplesite.com
33 | type: external
34 |
--------------------------------------------------------------------------------
/_docs/additional_resources/jeopardy_answer_key.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: API jeopardy answer key
3 | permalink: jeopardy_answer_key.html
4 | course: "Documenting REST APIs"
5 | weight: 14.6
6 | sidebar: docapis
7 | section: resources
8 | path1: resources.html
9 | last-modified: 2019-03-31
10 | ---
11 |
12 | {% include image_ad_right.html %}
13 |
14 | The API Jeopardy questions are in the [Conclusion section of Workshop Activities](https://idratherbewriting.com/learnapidoc/workshop.html#conclusion).
15 |
16 | {% if site.format == "print" %}
17 | *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.*
18 | {% endif %}
19 |
20 | {% if site.format == "web" %}
21 |
22 | ### Questions (jeopardy answer key)
23 |
24 | {% for item in site.data.jeopardy.list %}
25 |
26 |
27 |
28 |
{{item.question}}
29 |
30 | {% endfor %}
31 |
32 | {% endif %}
33 |
34 | {% include ads.html %}
35 |
--------------------------------------------------------------------------------
/_docs/additional_resources/resources.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "XV: Additional resources"
3 | permalink: resources.html
4 | course: "Documenting REST APIs"
5 | sidebar: docapis
6 | section: resources
7 | path1: resources.html
8 | weight: 14.0
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | This section contains additional exercises and information, such as more activities for calling APIs, or more info about alternative specifications. I also archive topics here that don't seem to fit well anywhere else.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/code_tutorials/docapiscode.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Code tutorials
3 | permalink: docapiscode.html
4 | keywords:
5 | course: "Documenting REST APIs"
6 | weight: 8.0
7 | sidebar: docapis
8 | section: docapiscode
9 | path1: doccode.html
10 | last-modified: 2023-05-28
11 | ---
12 |
13 | Documenting code poses one of the most challenging tasks for technical writers, especially if the writers don't have an engineering background or familiarity with the code. Even without deeper engineering expertise, you can still document code — everything from code snippets to full-fledged sample apps. This section explores techniques and strategies for documenting code.
14 |
15 | {% if site.format == "web" %}
16 | {: .tip}
17 | Download a PDF of this section.
18 | {% endif %}
19 |
20 | {% include minitoc.html %}
21 |
--------------------------------------------------------------------------------
/_docs/conceptual_topics_in_api_docs/docconceptual.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Conceptual topics in API docs
3 | permalink: docconceptual.html
4 | sidebar: docapis
5 | path1: docconceptual.html
6 | weight: 7.0
7 | course: "Documenting REST APIs"
8 | section: docconceptual
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | While reference topics in APIs generally receive the most attention, the conceptual topics, such as getting started tutorials, information about authorization, rate limiting, status and error codes, quick reference guides, and other topics constitute about half of the documentation. These topics are usually handled by technical writers more than engineers. You can evaluate the quality of API documentation in part by looking to see whether it includes these conceptual topics.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/documenting_api_endpoints/docendpoints.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Documenting API endpoints
3 | permalink: docendpoints.html
4 | sidebar: docapis
5 | path1: docendpoints.html
6 | weight: 3.0
7 | course: "Documenting REST APIs"
8 | section: docendpoints
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | Reference documentation for API endpoints consists of five general sections: resource descriptions, endpoints and methods, parameters, sample requests, and sample responses and schemas. To document the reference endpoints of an API, provide detailed information for each of these sections.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/documenting_api_endpoints/surfreport_endpoint.html:
--------------------------------------------------------------------------------
1 |
4 | curl -I -X GET "https://api.openweathermap.org/data/2.5/surfreport?zip=95050&appid=APIKEY&units=imperial&days=2"
5 |
6 |
7 | (In the above code, replace `APIKEY` with your actual API key.)
8 |
--------------------------------------------------------------------------------
/_docs/documenting_api_endpoints/surfreport_resource_description.html:
--------------------------------------------------------------------------------
1 |
Surfreport
2 |
3 |
Contains information about surfing conditions, including the surf height, water temperature, wind, and tide. Also provides an overall recommendation about whether to go surfing.
4 |
--------------------------------------------------------------------------------
/_docs/introduction_to_rest_apis/docapis_introtoapis.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Introduction to REST APIs
3 | permalink: docapis_introtoapis.html
4 | sidebar: docapis
5 | path1: docapis_introtoapis.html
6 | redirect_from:
7 | - /docapis_intro_to_rest_api_doc/
8 | weight: 1.0
9 | class: first
10 | last-modified: 2023-05-28
11 | ---
12 |
13 | REST APIs are flourishing in the marketplace, and the web is becoming a mashup of interconnected APIs. REST APIs consist of requests to and responses from a web server. Job prospects are hot for technical writers who can write developer documentation. This course will help you break into API documentation, especially if you complete the many portfolio-building activities.
14 |
15 | {% if site.format == "web" %}
16 | {: .tip}
17 | Download a PDF of this section.
18 | {% endif %}
19 |
20 | {% include minitoc.html %}
21 |
--------------------------------------------------------------------------------
/_docs/issues.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Log an Issue
3 | permalink: issues.html
4 | course: "Documenting REST APIs"
5 | sidebar: docapis
6 | type: plain
7 | progress: false
8 | no_newsletter: true
9 | last-modified: 2020-11-02
10 | ---
11 |
12 | To track issues and updates to the site, I'm using the [Issues log in GitHub](https://github.com/tomjoht/learnapidoc/issues).
13 |
14 | Log an issue in GitHub
15 |
16 | Issues can include any of the following:
17 |
18 | * Site errors
19 | * Typos or style issues
20 | * Incorrect content
21 | * Missing content
22 | * Outdated content
23 | * Suggested enhancements
24 |
25 | You can also [contact me](https://idratherbewriting.com/learnapidoc/contact.html){: .noCrossRef} with issues, requests, or other feedback.
26 |
--------------------------------------------------------------------------------
/_docs/metrics_and_measurement/docapis_metrics_and_measurement.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Metrics and measurement
3 | permalink: docapis_metrics_and_measurement.html
4 | course: "Documenting REST APIs"
5 | weight: 13.0
6 | sidebar: docapis
7 | section: metrics
8 | path1: docapis_metrics_and_measurement.html
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | 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.
13 |
14 | {% if site.format == "web" %}
15 |
16 | {: .tip}
17 | Download a PDF of this section.
18 | {% endif %}
19 |
20 | {% include minitoc.html %}
21 |
--------------------------------------------------------------------------------
/_docs/native_library_apis/nativelibraryapis.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Native library APIs
3 | permalink: nativelibraryapis.html
4 | sidebar: docapis
5 | path1: nativelibraryapis.html
6 | weight: 11.0
7 | course: "Documenting REST APIs"
8 | section: nativelibraryapis
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | Native library APIs refer to Java, C++, or other programming-specific APIs. In this model, rather than making requests across the web for the information, you download a library of code and integrate it into your project. The library is compiled directly into your application's build (rather than accessed through web protocols as with REST APIs). Although this type of API is less common, I include it here in part to clarify what makes REST APIs so different from native library APIs.
13 |
14 | {% if site.format == "web" %}
15 |
16 | {: .tip}
17 | Download a PDF of this section.
18 | {% endif %}
19 |
20 | {% include minitoc.html %}
21 |
--------------------------------------------------------------------------------
/_docs/newsletter-signup-confirmed.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Newsletter
3 | permalink: newsletter-signup-confirmed.html
4 | course: "Documenting REST APIs"
5 | sidebar: docapis
6 | type: plain
7 | progress: false
8 | last-modified: 2020-11-02
9 | ---
10 |
11 | Success! You subscribed to the I'd Rather Be Writing newsletter.
12 |
--------------------------------------------------------------------------------
/_docs/newsletter.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Newsletter
3 | permalink: newsletter.html
4 | course: "Documenting REST APIs"
5 | sidebar: docapis
6 | type: plain
7 | progress: false
8 | no_newsletter: true
9 | last-modified: 2023-05-28
10 | show_newsletter: never
11 | ---
12 |
13 | {% if page.show_newsletter != "never" %}
14 | {% include mailjet_embedded.html %}
15 | {% endif %}
16 |
17 |
22 |
27 |
--------------------------------------------------------------------------------
/_docs/openapi_spec_and_generated_ref_docs/pubapis_swagger_ui_standalone.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Swagger UI demo (standalone)
3 | permalink: pubapis_swagger_ui_standalone.html
4 | course: "Documenting REST APIs"
5 | sidebar: docapis
6 | section: restapispecifications
7 | path1: restapispecifications.html
8 | progress: false
9 | last-modified: 2018-08-02
10 | ---
11 |
12 |
13 |
14 | {% include random_ad2.html %}
15 |
16 | {% include ads.html %}
17 |
18 | {% include random_ad3.html %}
19 |
20 | {% include random_ad4.html %}
21 |
22 | {% include image_ad_right.html %}
23 |
--------------------------------------------------------------------------------
/_docs/openapi_spec_and_generated_ref_docs/restapispecifications.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenAPI spec and generated reference docs
3 | permalink: restapispecifications.html
4 | sidebar: docapis
5 | path1: restapispecifications.html
6 | weight: 4.0
7 | section: restapispecifications
8 | course: "Documenting REST APIs"
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | The OpenAPI specification provides a formal way of describing your REST API and includes all the reference sections mentioned in the previous section, Documenting API endpoints. Display frameworks such as Swagger UI can parse the OpenAPI specification and generate interactive documentation that lets users try out endpoints while learning about the API.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/pdf_frontmatter/pdf_copyright_page.html:
--------------------------------------------------------------------------------
1 | ---
2 | type: title
3 | permalink: pdf_copyright_page.html
4 | progress: false
5 | class: frontmatter
6 | last-modified: 2023-05-28
7 | ---
8 |
9 |
10 |
Copyright 2023. All rights reserved. No part of this publication may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the publisher, except in the case of brief quotations embodied in critical reviews and certain other noncommercial uses permitted by copyright law. For permission requests, contact Tom Johnson at tomjoht@gmail.com.
Tom Johnson
22 | idratherbewriting.com/learnapidoc
23 |
{{site.attribution}}
24 |
{{site.subparagraph}}
25 | {% endif %}
26 |
27 |
--------------------------------------------------------------------------------
/_docs/processes_and_methodology/docapis_managing_doc_processes.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Documentation processes and methodology
3 | permalink: docapis_managing_doc_processes.html
4 | course: "Documenting REST APIs"
5 | weight: 12.0
6 | sidebar: docapis
7 | section: devportals
8 | path1: docapis_managing_doc_processes.html
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | The process for managing developer portal documentation includes a number of different tasks outside of content development. The role of a DX (developer experience) content strategist plays a key role in defining workflows, standards, user flows, processes, and other aspects of the site. workflows for different types of documentation. In this section, I cover details for how to manage the doc work, including processes for fixing doc bugs versus tackling larger doc projects. I also explain processes for releasing SDKs, managing external contributions, and more.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/publishing_api_documentation/publishingapis.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Publishing your API documentation
3 | permalink: publishingapis.html
4 | sidebar: docapis
5 | path1: publishingapis.html
6 | section: publishingapis
7 | weight: 9.0
8 | course: "Documenting REST APIs"
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | API documentation often follows a docs-as-code workflow, where the tools to author and publish documentation align closely with the same tools developers use to write, manage, build, and deploy code. Docs-as-code involves using lightweight formats such as Markdown, collaborating through Git or other version control, building your doc site with a static site generator, and deploying it through a continuous build model, where the build happens on the server when you push commits to a particular branch.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/success.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: page
3 | title: Subscription Success!
4 | permalink: /success/
5 | show_newsletter_signup: nope
6 | ---
7 |
8 | Thanks for subscribing to I'd Rather Be Writing! You're on track to stay updated about the latest trends, methods, and best practices in technical writing, especially API documentation!
9 |
10 | Expect to receive regular emails from tjohnson@idratherbewriting.com. In the meantime, feel free to browse the newsletter archives:
11 |
12 |
17 |
22 |
--------------------------------------------------------------------------------
/_docs/testing_api_docs/testingdocs.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Testing API documentation
3 | permalink: testingdocs.html
4 | sidebar: docapis
5 | path1: testingdocs.html
6 | weight: 6.0
7 | section: testingdocs
8 | course: "Documenting REST APIs"
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | Testing your documentation is critical to providing accurate, thorough information. With API and developer docs, due to the high level of complexity and engineering requirements, technical writers might be inclined to simply take information that engineers give them and incorporate it wholesale, without personally testing it. Merely playing an editorial/publishing function, however, can reduce your role to that of an engineer's secretary.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/thank-you-for-donating.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Thank you for donating"
3 | permalink: thank-you-for-donating.html
4 | course: "Documenting REST APIs"
5 | sidebar: docapis
6 | progress: false
7 | last-modified: 2020-11-02
8 | ---
9 |
10 | Thank you for donating. Your support helps drive more time and energy into this course and also helps make this course available online for free.
11 |
12 | Tom Johnson
13 |
--------------------------------------------------------------------------------
/_docs/the_writing_process/writing_process.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "The writing process"
3 | permalink: writing_process.html
4 | course: "Documenting REST APIs"
5 | weight: 8.91
6 | sidebar: docapis
7 | section: writing_process
8 | path1: writing_process.html
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | The writing process refers to the way you write and develop content. There are five main steps to the writing process: planning, information gathering, writing, reviewing, and publishing. Although these aspects of the writing process are general to almost every type of writing, in this section I tailor the information to be specific to writing technical documentation.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/thriving_in_the_api_doc_space/docapis_work_on_conceptual_topic.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Activity: Create or fix an API reference documentation topic"
3 | permalink: docapis_work_on_conceptual_topic.html
4 | course: "Documenting REST APIs"
5 | weight: 10.5
6 | sidebar: docapis
7 | section: jobapis
8 | path1: jobapis.html
9 | last-modified: 2019-11-17
10 | ---
11 |
12 | {% include image_ad_right.html %}
13 |
14 | This part of the activity might be challenging, but here is where you'll start building some examples for your portfolio.
15 |
16 | 1. In the same project as before, identify one of the API reference topics that needs help. (If the API has a new reference endpoint to document, focus on this endpoint.)
17 | 2. Edit the topic to improve it. (If it's a new endpoint, write the documentation for it.)
18 | 6. Create a [pull request](https://idratherbewriting.com/learnapidoc/pubapis_github_pull_requests.html) and contribute your edits to the project.
19 |
20 | {% include ads.html %}
21 |
22 | {% include random_ad3.html %}
23 |
24 | {% include random_ad4.html %}
25 |
26 | {% include random_ad2.html %}
27 |
--------------------------------------------------------------------------------
/_docs/thriving_in_the_api_doc_space/jobapis.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Thriving in the API doc space
3 | permalink: jobapis.html
4 | sidebar: docapis
5 | path1: jobapis.html
6 | weight: 10.0
7 | course: "Documenting REST APIs"
8 | section: jobapis
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | Getting an API documentation job and thriving requires you to demonstrate your technical aptitude through a writing portfolio. The portfolio should include samples of documentation written for developers. One way to build this portfolio is by working on an open-source project. You also need to live in a tech hub where API documentation jobs are available, such as California, Texas, New York, or Virginia. Overall, thriving in the developer documentation space requires you to continually learn a healthy dose of code, which can be challenging.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 | {% endif %}
18 |
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_docs/using_an_api_like_a_developer/likeadeveloper.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Using an API like a developer
3 | permalink: likeadeveloper.html
4 | sidebar: docapis
5 | path1: likeadeveloper.html
6 | weight: 2.0
7 | section: likeadeveloper
8 | course: "Documenting REST APIs"
9 | last-modified: 2023-05-28
10 | ---
11 |
12 | Playing a brief role as a developer will help you understand developer needs better, as well as what developers typically look for in API documentation. Developers often use tools such as Postman or curl to make calls. They look at the structure of the response, and they dynamically integrate the needed information into web pages and other applications.
13 |
14 | {% if site.format == "web" %}
15 | {: .tip}
16 | Download a PDF of this section.
17 |
18 | {% endif %}
19 | {% include minitoc.html %}
20 |
--------------------------------------------------------------------------------
/_drafts/docapis_when_code_is_too_complex_to_understand.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: When code is too complex to understand
3 | permalink: docapiscode.html
4 | keywords:
5 | course: "Documenting REST APIs"
6 | sidebar: docapis
7 | section: docapiscode
8 | path1: doccode.html
9 | published: false
10 | last-modified: 2020-11-02
11 | ---
12 |
13 |
14 | 17. *Could you adopt some form of pair programming that involves recording what the engineer does so that you can go back and later learn it? Isn’t that the ideal compromise?*
15 |
16 | *How familiar do you need to be with the code to make sense of it? Somewhat but not 100%. I think if you can understand the fundamentals, then others can talk you through the rest.*
17 |
18 | *Is documenting code the most fun thing, or the least? It is quite fun because you can make it work.*
19 |
20 | *How do you know what’s obvious and not in code?*
21 |
--------------------------------------------------------------------------------
/_includes/amazon_book.html:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/tomjoht/learnapidoc/abb7b0e23018edb21b6d40ea6c62f2662e0ca75c/_includes/amazon_book.html
--------------------------------------------------------------------------------
/_includes/audio.html:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/_includes/commento.html:
--------------------------------------------------------------------------------
1 | {% unless page.focus == "noform" %}
2 |
3 |
4 |
5 | {% endunless %}
6 |
--------------------------------------------------------------------------------
/_includes/content/jeopardy_questions.md:
--------------------------------------------------------------------------------
1 | This is a jeopardy game to test your learning. To play jeopardy, you're given an answer. You have to supply the question. For example, if the answer is "a device on your wall that shows the time," the question might be, "What is a clock?"
2 |
3 | **Answers**
4 |
5 | {% for item in site.data.jeopardy.list %}
6 |
7 |
8 |
9 |
{{item.answer}}
10 |
11 | {% endfor %}
12 |
13 | You can find the answer key [here](jeopardy_answer_key.html).
14 |
--------------------------------------------------------------------------------
/_includes/content/troubleshooting_spec_tip.md:
--------------------------------------------------------------------------------
1 | {: .tip}
2 | If you get stuck, see the [sample OpenAPI spec here](https://idratherbewriting.com/learnapidoc/docs/openapi_spec_and_generated_ref_docs/openapi_openweathermap.yml) for the fully working sample. This will help you spot and troubleshoot indentation or other errors.
3 |
--------------------------------------------------------------------------------
/_includes/course_image.html:
--------------------------------------------------------------------------------
1 | {% if site.format == "print" %}{% if {{include.url}} %}{% endif %}{% if {{include.url}} %}{% endif %}{% if {{include.caption}}%}{{include.caption}}{% endif %}{% elsif site.format == "web" %}{% if {{include.url}} %}{% endif %}{% if {{include.url}} %}{% endif %}{% if {{include.caption}}%}{{include.caption}}{% endif %}{% endif %}
2 |
--------------------------------------------------------------------------------
/_includes/disqus.html:
--------------------------------------------------------------------------------
1 | {% if site.format == "web" %}{% unless page.focus == "noform" %}
2 |
3 |
14 |
15 | {% endunless %}{% endif %}
16 |
--------------------------------------------------------------------------------
/_includes/donate_button.html:
--------------------------------------------------------------------------------
1 | {% if site.format == "web" %}
2 |
Donate?
3 |
Want to buy me lunch? Click the Donate button below to donate any amount through Paypal. Or log an issue or submit a pull request in GitHub to improve this content.
{% if {{include.url}} %}{% endif %}{% if {{include.caption}}%}
{% if {{include.url}} %}{% endif %}{% if {{include.caption}}%}
4 | {% endif %}
5 | {% endcomment %}
6 |
--------------------------------------------------------------------------------
/_includes/versions.html:
--------------------------------------------------------------------------------
1 | {% if page.versions %}
2 | {% assign versionsList = page.versions %}
3 |