add styles for pdf output

Author: tomjoht

_docs/openapi_spec_and_generated_ref_docs/pubapis_openapi_intro.md

@@ -90,7 +90,7 @@ Learning the OpenAPI spec and constructing the YAML or JSON code by hand the fir
 
 Before we dive into ways to manually create the OpenAPI specification document, it's worth noting some other approaches to the task, beyond choosing whether to use a visual editor or manually write the code. You can also choose to auto-generate the OpenAPI spec from annotations in your programming code. This developer-centric approach may make sense if you have a large number of APIs or if it's not practical for technical writers to create this documentation. In my [2020 Developer Documentation Trends survey](https://idratherbewriting.com/learnapidoc/docapis_trends.html), approaches for auto-generating the spec versus manually generating it were split:
 
-<figure><a target="_blank" class="noExtIcon" href="docapis_trends.html"><img class="docimage medium border" src="{{site.media}}/trends-generating-openapi.png" alt="Percentage of auto-generation versus manual creation"></a><figcaption>Percentage of auto-generation versus manual creation</figcaption></figure>
+<figure><a target="_blank" class="noExtIcon" href="https://idratherbewriting.com/learnapidoc/docapis_trends.html"><img class="docimage medium border" src="{{site.media}}/trends-generating-openapi.png" alt="Percentage of auto-generation versus manual creation"></a><figcaption>Percentage of auto-generation versus manual creation</figcaption></figure>
 
 If you want to go the code-generation route, Swagger offers a variety of libraries that you can add to your programming code to generate the specification document. These Swagger libraries then parse the annotations that developers add and generate the OpenAPI specification document. These libraries are considered part of the ["Swagger Codegen"](https://swagger.io/swagger-codegen/) project. The annotation methods vary based on the programming language. For example, here's a [tutorial on annotating code with Swagger for Scalatra](http://www.infoq.com/articles/swagger-scalatra).
 

_docs/thriving_in_the_api_doc_space/docapis_find_open_source_project.md

@@ -34,7 +34,7 @@ Finding the right project can be challenging, but it is critical to your portfol
 
 The ideal open-source API project should meet the following criteria. The project should:
 
-* Involve a REST API (not a [library-based API](nativelibraryapis_overview.html) or some other developer tool that isn't an API).
+* Involve a REST API (not a [library-based API](https://idratherbewriting.com/learnapidoc/nativelibraryapis_overview.html) or some other developer tool that isn't an API).
 * Have some documentation needs.
 * Not be so technical that it's beyond your ability to learn it. (If you already have familiarity with a programming language, you might target projects that focus on that language.)
 * Be active, with a somewhat recent commit.
@@ -56,7 +56,7 @@ To find an open-source project with API doc needs:
 
 4.  Click **Search** and browse [the results](https://github.com/search?q=api+documentation+label%3A%22help+wanted%22&type=Issues).
 
-    In the results, you might want to look for a *REST API* project (rather than a [native-library API]({{site.rooturl}}nativelibraryapis_overview.html) such as a Java API). Developers don't often distinguish between the two with requests related to API documentation. If you see doc requests related to Java, C++, JavaScript, or some other programming-specific framework (with no identifiable endpoints), it's probably not a REST API. However, working on such a project could be equally fulfilling as a learning opportunity. It depends on what you're interested in.
+    In the results, you might want to look for a *REST API* project (rather than a [native-library API](https://idratherbewriting.com/learnapidoc/nativelibraryapis_overview.html) such as a Java API). Developers don't often distinguish between the two with requests related to API documentation. If you see doc requests related to Java, C++, JavaScript, or some other programming-specific framework (with no identifiable endpoints), it's probably not a REST API. However, working on such a project could be equally fulfilling as a learning opportunity. It depends on what you're interested in.
 
     As you browse the results, are there any projects that look interesting or promising? If so, great. If not, adjust some of the keywords and keep looking.
 
@@ -85,15 +85,15 @@ To find an open-source project with API doc needs:
 
 ## Recognizing the type of API used in the project
 
-When you look for API projects, recognize that there are many different types of APIs. Many of the APIs you run across might be [native library APIs](nativelibraryapis_overview.html), which don't use web protocols to make requests and responses (as REST APIs do) but rather involve incorporating a language-specific library into the project. If the API seems to focus on a particular language, and the API documentation looks auto-generated, it's probably a native-library API.
+When you look for API projects, recognize that there are many different types of APIs. Many of the APIs you run across might be [native library APIs](https://idratherbewriting.com/learnapidoc/nativelibraryapis_overview.html), which don't use web protocols to make requests and responses (as REST APIs do) but rather involve incorporating a language-specific library into the project. If the API seems to focus on a particular language, and the API documentation looks auto-generated, it's probably a native-library API.
 
 {% include image_ad_right.html %}
 
 On the other hand, if the project's documentation contains these core reference sections for their endpoints, it's probably a REST API.
 
 ## Contributing will require Git skills
 
-When you later contribute to the open-source project, you will need to understand the basic [Pull request Git workflow](pubapis_github_pull_requests.html). Understanding the Git workflow might require you to ramp up on [Git tutorials](https://www.atlassian.com/git/tutorials) a bit first, but there's no better way to learn Git than by actively using it in a real project scenario.
+When you later contribute to the open-source project, you will need to understand the basic [Pull request Git workflow](https://idratherbewriting.com/learnapidoc/pubapis_github_pull_requests.html). Understanding the Git workflow might require you to ramp up on [Git tutorials](https://www.atlassian.com/git/tutorials) a bit first, but there's no better way to learn Git than by actively using it in a real project scenario.
 
 Don't worry so much about Git now. You can learn these skills later when you have content you're ready to contribute. For now, just find a project.
 
@@ -132,4 +132,4 @@ For a tutorial on pull requests workflows with GitHub projects, see [Pull reques
 
 ## Next steps
 
-After you find an open-source project, go to the next activity: [Evaluate API reference docs for core elements](docapis_api_reference_activity.html).
+After you find an open-source project, go to the next activity: [Evaluate API reference docs for core elements](https://idratherbewriting.com/learnapidoc/docapis_api_reference_activity.html).

_docs/thriving_in_the_api_doc_space/docapis_work_on_conceptual_topic.md

@@ -15,7 +15,7 @@ This part of the activity might be challenging, but here is where you'll start b
 
 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.)
 2.  Edit the topic to improve it. (If it's a new endpoint, write the documentation for it.)
-6.  Create a [pull request](pubapis_github_pull_requests.html) and contribute your edits to the project.
+6.  Create a [pull request](https://idratherbewriting.com/learnapidoc/pubapis_github_pull_requests.html) and contribute your edits to the project.
 
 {% include ads.html %}
 

_docs/thriving_in_the_api_doc_space/jobapis_learning_code.md

@@ -20,7 +20,7 @@ With developer documentation roles, some level of coding is required. But you do
 
 When faced with these multi-language documentation challenges, hiring managers often search for technical writers who are former programmers to do the tasks. There are a good number of technical writers who were once programmers, and they can command more respect and competition for these developer documentation jobs.
 
-But even developers will not know more than a few languages. Finding a technical writer who commands a high degree of English language fluency in addition to possessing in-depth technical knowledge of Java, Python, C++, .NET, Ruby, in addition to mastering [docs tools](pubapis_docs_as_code.html) to facilitate the authoring/publishing process from beginning to end is like finding a unicorn. (In other words, these technical writers don't really exist.)
+But even developers will not know more than a few languages. Finding a technical writer who commands a high degree of English language fluency in addition to possessing in-depth technical knowledge of Java, Python, C++, .NET, Ruby, in addition to mastering [docs tools](https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html) to facilitate the authoring/publishing process from beginning to end is like finding a unicorn. (In other words, these technical writers don't really exist.)
 
 If you find one of these technical writers, the person is likely making a small fortune in contracting rates and has a near limitless choice of jobs. Companies often list knowledge of multiple programming languages as a requirement, but they realize they'll never find a candidate who is both a William Shakespeare and a Steve Wozniak.
 
@@ -94,15 +94,15 @@ Here's a transcript of two questions in their exchange (cleaned up a bit for rea
 
 Keep in mind that Davis and Neiman are trying to persuade more European countries to use Synergistech as their recruiting agency to find and hire API tech writers, so they're presenting the need for engineering-savvy tech writers. These super tech-savvy writers are harder to find — hence the need for expert recruiters. Regardless of the agenda, Neiman and Davis argue for a higher level of coding proficiency than Wood or Rhea.
 
-The level of coding knowledge required no doubt depends on the position, environment, and expectations at your company. Perhaps if the tech writer doesn't have more of an engineering background, engineers will just send the tech writer [code snippets](docapis_codesamples_bestpractices.html) to paste into the docs. But without the technical acumen to fully understand, test, and integrate the code in meaningful ways, the tech writer will be at the mercy of engineers and their terse explanations or cryptic inline comments. The tech writer's role will be reduced to being an editor/publisher instead of a writer.
+The level of coding knowledge required no doubt depends on the position, environment, and expectations at your company. Perhaps if the tech writer doesn't have more of an engineering background, engineers will just send the tech writer [code snippets](https://idratherbewriting.com/learnapidoc/docapis_codesamples_bestpractices.html) to paste into the docs. But without the technical acumen to fully understand, test, and integrate the code in meaningful ways, the tech writer will be at the mercy of engineers and their terse explanations or cryptic inline comments. The tech writer's role will be reduced to being an editor/publisher instead of a writer.
 
 In my experience, Neiman's explanation about developers instructing tech writers to create similar code in other languages (based on a 15-minute over-the-shoulder conversation at the engineer's desk) goes too far. Although I've created simple JavaScript code samples (based on a pattern the engineers showed me), I've never been asked to create code samples across other languages. I could auto-generate code snippets for web API requests (using Postman), but to develop code across multiple languages tends to be more of the programmer's responsibility, not the tech writer's.
 
 {% include ads.html %}
 
 Neiman goes on to say that in one company, he tested out the code from engineers and found that much of it relied on programs, utilities, or other configurations already set up on the developers' computers. As such, the engineers were blind to the initial setup requirements that users would need to run the code properly. Neiman says this is one danger of simply copying and pasting the code from engineers into documentation. While it may work on the developer's machine, it will often fail for users.
 
-This comment from Neiman does ring more true to me. As I argued for extensively in [Testing your API documentation](testingdocs.html), you have to be able to test the endpoints, code samples, and SDKs in order to write and evaluate the documentation. It is usually true that programmers (who set up their machines months ago) have long forgotten or can't even identify all the frameworks, configurations, and other utilities they installed to get something working. The more technical you are, the more powerful of a role you can play in shaping the information.
+This comment from Neiman does ring more true to me. As I argued for extensively in [Testing your API documentation](https://idratherbewriting.com/learnapidoc/testingdocs.html), you have to be able to test the endpoints, code samples, and SDKs in order to write and evaluate the documentation. It is usually true that programmers (who set up their machines months ago) have long forgotten or can't even identify all the frameworks, configurations, and other utilities they installed to get something working. The more technical you are, the more powerful of a role you can play in shaping the information.
 
 Neiman is a former engineer and says that during his career, he has probably worked with 20-25 different programming languages. Being able to learn a new language quickly and get up to speed is a key characteristic of his tech comm consulting success, he says.
 
@@ -149,7 +149,7 @@ Keep in mind that your level of involvement with editing, publishing, and author
 
 If you're stuck in the publishing/editing area, you can interview engineers at length about what's going on in the code (record these discussions — Evernote has a nifty recording feature built-in that I've used multiple times for just this purpose), and then try your best to describe the actions in as clear speech as possible. You can always fall back on the idea that for those users who need Python, the Python code should look somewhat familiar to them. Well-written code should be, in some sense, self-descriptive in what it's doing. Unless there's something odd or non-standard in the approach, engineers fluent in code should be able to get a sense of how the code works.
 
-In your documentation, you'll need to focus on the higher-level information, the "why" behind the approach, highlighting of any non-standard techniques, and the general strategies behind the code. You can get this *why* by asking developers for the information in informational interviews. The details of *what* will either be apparent in the code or can be minimized. (See [Code samples and tutorials](docapis_codesamples_bestpractices.html) for details.)
+In your documentation, you'll need to focus on the higher-level information, the "why" behind the approach, highlighting of any non-standard techniques, and the general strategies behind the code. You can get this *why* by asking developers for the information in informational interviews. The details of *what* will either be apparent in the code or can be minimized. (See [Code samples and tutorials](https://idratherbewriting.com/learnapidoc/docapis_codesamples_bestpractices.html) for details.)
 
 As you decide how much detail to include, remember that even though your audience consists of developers, it doesn't mean they're all experts with every language. For example, the developer may be a Java programmer who knows just enough iOS to implement something on iOS, but for more detailed knowledge, the developer may be depending on code samples in the documentation. Conversely, a developer who has real expertise in iOS might be winging it in Java-land and relying on your documentation to pull off a basic implementation.
 
@@ -186,8 +186,8 @@ Even so, this pomodoro technique for focus doesn't solve the problem. It's still
 There are a lot of questions about just how to learn code, and I don't have all the answers. But here's what I know:
 
 *  Developer documentation requires familiarity with code, though exactly how much expertise you need is debatable.
-*  You have to understand explanations from engineers, including the [terms used](docapis_glossary_section.html). The explanations in your documentation should focus on the *why* more than the *how*.
-*  You should be able to [test code](testingdocs_overview.html) from engineers so that you can identify assumptions that engineers are often blind to.
+*  You have to understand explanations from engineers, including the [terms used](https://idratherbewriting.com/learnapidoc/docapis_glossary_section.html). The explanations in your documentation should focus on the *why* more than the *how*.
+*  You should be able to [test code](https://idratherbewriting.com/learnapidoc/testingdocs_overview.html) from engineers so that you can identify assumptions that engineers are often blind to.
 *  To thrive in an API documentation career, you have to incorporate a regiment of continual learning.
 *  Completing several pomodoros a day over the course of weeks and months can result in significant progress in building your technical understanding.
 
@@ -203,7 +203,7 @@ However, take consolation in the fact that your job is not to code but rather to
 
 For more information about working with code, see these two topics:
 
-* [SDKs](docapis_sdks.html)
-* [Code samples and tutorials](docapis_codesamples_bestpractices.html)
+* [SDKs](https://idratherbewriting.com/learnapidoc/docapis_sdks.html)
+* [Code samples and tutorials](https://idratherbewriting.com/learnapidoc/docapis_codesamples_bestpractices.html)
 
 Let's look at one more topic in this jobs section: [Locations for API doc writer jobs](jobapis_location.html).

_docs/thriving_in_the_api_doc_space/jobapis_location.md

@@ -763,4 +763,4 @@ In this activity, you'll get a sense of the skills needed for the jobs in your l
     *  Portfolio with writing samples that include developer documentation
     *  Technical knowledge related to developer domain
     *  Experience writing developer documentation
-7.  Make a plan for how you'll match up your portfolio, tech knowledge, and experience related to what these job descriptions are asking for. You might need to dedicate more time to an [open-source documentation project]({{site.rooturl}}docapis_find_open_source_project.html) to build up the needed skills.
+7.  Make a plan for how you'll match up your portfolio, tech knowledge, and experience related to what these job descriptions are asking for. You might need to dedicate more time to an [open-source documentation project](https://idratherbewriting.com/learnapidoc/docapis_find_open_source_project.html) to build up the needed skills.