Reverse engineering the recipe for excellent documentation

You're a prompt engineer who will reverse engineer a prompt from some provided content. In this scenario, you'll reverse engineer a prompt for an API overview, which will form part of some technical documentation for developers. Although you'll reverse engineer the prompt from specific content, the prompts you develop should be more generalized and not specific to the particular example API. You'll go section by section rather than all at once. But so you can see the big picture, here's the sample API overview:

{Sample API Overview}

[paste in the content from https://developers.google.com/maps/documentation/routes/overview]

{Instruction}

Develop a prompt that would yield content for the first section — the intro text directly under the "Routes API Overview" title. Be extremely specific and granular about what instructions to provide to an AI to produce just such an overview, down to the sentence style and structure and length.

Now proceed to the next section, "Why use the Routes API." Again, be excruciatingly specific and descriptive in the prompt, remembering that this instruction will need to be generalized to something other than the Routes API. The audience is developers.

Nice work! You're really helpful. Now let's move on to the next section, "What you can do with the Routes API?" Again, remember that this prompt you're building will be more general than the specific Routes API, so describe the pattern, style, topic categories, and other details here.

Your response looks great! Now move on to the next section, "How the Routes API works." Remember that this is an overview, so while you should be detailed and specific, this "how it works" part is still very high level because it's in the overview.

Nice work! Now move on to the next section: "Resources."

Do the same for the next section, "How to use the Routes API."

Great job! Now continue on to the next section, "Available client libraries."

Looking great! Now keep going with the last section, "What's Next."

You're a technical writer creating an API overview document for a developer audience. The API overview provides a high-level description of the API and follows a standard template with sections that I'll carefully define for you.

You'll go section by section as you write this, carefully following a defined structure and style that I specify, rather than writing the whole overview at once. Additionally, this is of paramount importance: you should draw your information from the {Source Material} I provide. Do not invent or guess information if it doesn't exist in the source material. Accuracy based on information from the {Source Material} is the highest priority. If the template calls for information not in the {Source Material}, just write something like "Information not found in source." Then I'll go back to those sections later and fill in the details.

So you can see the big picture of the shape of the API overview, here's a sample overview from another API. This is just an example.

{Sample API Overview}

[paste in the content from https://developers.google.com/maps/documentation/routes/overview]

Here's the source material from which you should get your information and facts:

{Source Material}

[paste in all the content you can find — reference material, one-pagers, engineering design docs, product definition docs, etc.]

{Instruction}

Now let's start with the introductory section. Here's the template you should follow. Populate this template with information from the {Source Material}.

Introductory Section

Context: You're writing a concise and informative overview of a technical API for developers. This section serves as the introduction to the API and appears directly beneath the API title.

Content Instructions:

• Begin with a succinct definition of the API. Use the following structure: "The [API Name] is a [type of service] that [briefly describes its core function]."
  • Example: "The Routes API is a service that calculates optimal routes between locations based on various factors such as transportation mode and real-time traffic."
• Elaborate on the primary benefit or use case for the API. Highlight its value proposition and the context in which someone would use it.
  • Example: "With the Routes API, developers can provide users with accurate and efficient directions tailored to their specific needs."

Style and tone instructions:

• Technical but Aacessible — Avoid overly complex jargon, but ensure accurate technical terminology.
• Concise and informative — Every sentence should deliver clear value.
• Active voice and present tense: Use active voice and write in the present tense.
• Sentence length — Aim for sentences between 10-20 words for maximum clarity.
• Target audience: Keep in mind that your audience consists primarily of developers.
• Point of view: Speak directly to developers using the second-person ("you") point of view.

Nice job! I really like how detailed you are, and how you're sticking with the information in the source material. Accuracy is highly important to me, as each detail in this documentation must be correct. Your tone and style are just right — clear and direct, but also friendly and detailed for a developer audience. Now proceed to the next section, "Why use the API." Here's the template you should follow. Populate this with information from the {Source Material}.

"Why Use This API" Section

Context: Building upon the introduction, this section aims to convince developers of the API's value proposition. It should highlight the key benefits and advantages that set the API apart. This section immediately follows the introductory section and is titled "Why use the [API Name]."

Content Instructions:

• Opening Sentence: Begin with a clear topic sentence that indicates the section's purpose. Example: "The [API Name] lets you [insert broad purpose of the API]."
• Subsequent Sentences (3-5): Delve into specific advantages. Use the following structures:
  • "[Benefit] — Elaborate on the benefit." Example: "Improved accuracy — Get real-time data for up-to-the-minute route information."
  • "[Feature] allows developers to [outcome]." Example: "Customizable routing profiles lets you tailor routes based on specific criteria like vehicle type or environmental considerations."
  • "The API lets you [specific capability of the API]."

Style and tone instructions:

• Persuasive and informative: Clearly articulate the advantages of using the API while maintaining a technical tone suitable for a developer audience.
• Active voice: Use active voice to make the writing more direct and engaging.
• Feature focus: Emphasize the capabilities and features rather than making generalized statements.
• Bullet points: Pepper in bullet points now and then to make the content easier to read.
• Straightforward language: Use straightforward language and avoid business cliches including words like "leverage," "harness," "innovative," "robust." Use few adjectives if any, as this is technical documentation meant to instruct, not persuade.

Nice work! You're really smart and articulate. I especially like how you're structuring the information for easy readability. Now let's move on to the next section, "What you can do with this API"? Here's the template you should follow. Populate this with information from the {Source Material}.

"What You Can Do With This API" Section

Context: This section provides a comprehensive overview of the API's functionalities. Aim to showcase the breadth of possibilities and inspire developers to envision potential use cases within their own projects and provide concrete examples of the API's capabilities. This section naturally follows the "Why Use" section.

Content Instructions:

• Opening Sentence: Start with a clear and engaging topic sentence that encapsulates the section's purpose: what the API lets developers achieve."
• Subsequent Sections (2-4): Break down the API's functionalities into logical categories with descriptive subheadings.
  • Subheading: Use clear and concise subheadings to introduce each category of functionality.
  • Explanation: Under each subheading, provide 2-3 sentences that expand on the capabilities, providing specific examples of use cases for context.
  • Example structure: "[Category Name] — [Brief explanation of category]. For instance, you can use the API to [specific action #1], [Specific action #2], or [specific action #3]."

Style and tone instructions

• Informative and inspiring: Write with an enthusiastic and informative tone, highlighting the API's versatility and potential for innovation.
• Active voice and present tense: Maintain active voice and present tense for clarity and engagement. Avoid using the word "will" or any future tense.
• Structure and organization: Employ clear subheading, bullet points, or numbered lists to enhance readability.
• Examples:Consider the use of examples to provide context and clarity for each capability.

Your response looks great! I don't want to make you blush, but you have natural talent as a technical writer. Really! You're sticking to the information in the {Source Material} and I like it. You're also writing with clarity and straightforwardness in a pleasing-to-read way. Now let's move on to the next section, "How the [API name] works." Remember that this is an overview, so while you should be detailed and specific, this "How it works" part is still very high level as it is in the overview. Here's the template you should follow. Draw upon the information in the {Source Material} for your content.

"How the [API Name] Works" section

Context: This section provides a high-level technical explanation of the API's underlying mechanisms without delving into intricate details, offering developers a clear understanding of the API's core processes. This section should come after the use cases section.

Content instructions

• Subsequent sections (2-4): Divide the API's processes into 2-4 key steps or stages with descriptive subheadings.
  • Distinct methods/endpoints: If the API provides distinct methods or endpoints (like ComputeRoute and ComputeRouteMatrix), each of these can have its own subheading.
  • Sequential steps: If the API functions as a series of sequential steps, use these as subheaders instead.
• Subheading: Craft clear and informative subheaders for each stage or method.
• Explanation: Under each subheader, offer 2-3 sentences outlining the step's function or how the method works. Focus on the input, processing, and output of each stage.
• Code example (optional): Provide a code example (in a collapsible section or with syntax highlighting) that illustrates how to make a request for each method of the API. Ensure the code example is well-formatted and easy to understand.
• Example structure: "[Stage/Method Name] — [Brief explanation]. The API accepts [input], processes it using [method or technology], and returns [output]."

Style and tone instructions

• Technical yet approachable: Maintain a technical tone while ensuring the content is understandable for developers with varying levels of familiarity with the subject matter.
• Clarity and simplicity: Focus on conveying the essence of each step without overwhelming it with excessive detail. Use clear and simple language, avoiding unnecessary jargon.
• Active voice and present tense: Stick with active voice and present tense for a more engaging and direct tone.

Nice work! I'm really digging this content and your Strunk-and-White-like style. Maintaining a sense of simple English grammar really helps developers from all backgrounds understand the material. Now let's move on to the next section: "Resources." Here's the template you should follow. Populate this with information from the {Source Material}.

"Resources" section

Context: The "Resources" section serves as a directory, pointing developers toward additional information and tools related to the API. It's a pivotal part of the overview, offering quick access to essential assets and should be located near the end of the overview.

Content Instructions:

• Introduction (optional): You can choose to open this section with a brief introductory sentence, like: "The [API Name] provides a range of resources to aid developers in successful integration."
• Resource presentation: Present resources in an organized and accessible manner. This should ideally be represented with a table (note: actual table syntax is not used here due to format limitations, but would typically include the use of table tags in HTML). The content should include:
  • Resource name: Clearly state the name or title of the resource. Get this from the API's reference documentation if possible.
  • Description: Provide a concise explanation of what the resource offers, its purpose or content, and what the developer will gain by using it.
  • Format/access: Indicate the format of the resource (e.g., JSON, XML), or how it's accessed.

Style and tone instructions:

• Scannable and informative: Prioritize clarity and ease of navigation. Developers should be able to identify the resources relevant to their needs.
• Concise: Keep descriptions brief and focused, providing only essential information.

I like it! Now do the same for the next section, "How to use the Routes API." Remember, if the information doesn't exist in the {Source Material}, don't make it up. Just either skip that section or write "Not enough information in the source." Here's the template you should follow. Populate this with information from the {Source Material}.

"How to Use the [API Name]" Section

Context: This crucial section provides a roadmap for developers, guiding them through the initial steps of integrating the API. It should offer a clear, step-by-step introduction to getting started with the API, located towards the end of the overview before the resources section.

Content instructions:

1. Opening sentence (optional): Start with a concise and inviting opening line such as "Integrating the [API Name] into your project involves several steps."
2. Step-by-step guide: Outline the essential steps in a numbered list or ordered list with brief descriptions.
   1. Step: Clearly state the action to be taken. Example: "Obtain API Credentials."
   2. Description: Provide 1-2 sentences elaborating on the step, outlining any necessary actions: "Visit the Google Cloud Console to create a new project or select an existing one, and enable the Routes API."
3. Closing sentence (optional): Conclude with an encouraging note: "With these initial steps complete, you're ready to start building with the [API Name]."

Style and tone instructions:

• Instructive and encouraging: Adopt a friendly and supportive tone, guiding developers with clear, actionable instructions. Break down complex processes into manageable steps.
• Active voice: Use active voice to make your instructions more direct and comprehensible.
• Numbered list or ordered list: Use a numbered list or ordered list to emphasize the sequential nature of the steps.

Great job! You're a natural. Would you like to come join our technical writing team? I'm being serious (wink wink). Now continue on to the next section, "Available client libraries." Here's the template you should follow. Populate this with information from the {Source Material}.

"Available Client Libraries" Section

Context: This section informs developers about the available client libraries that can simplify their interaction with the API. It typically includes a list of supported programming languages and links to the respective libraries. This section can be brief and should be located near the end of the overview.

Content Instructions:

• Introductory Sentence: Begin with a simple sentence like, "[API Name] supports a variety of client libraries to streamline your development process."
• List of Libraries: Present the available client libraries. You can choose to do this in paragraph form, as a list or in a table with columns for:
  • Programming Language: Clearly state the name of the programming language.
  • Link: If applicable, provide a hyperlink to the library's documentation or repository.

Style and tone instructions:

• Informative and direct: Keep this section brief and to the point, offering essential information without unnecessary elaboration.

Although we were careful to follow a defined template and structure, now let's examine whether we missed anything that should belong in the overview. Are there any details or characteristics that you think should belong in this API overview that we skipped over? Any important high-level information that developers using this API should know? Provide it here.