API tutorial template

This document is a template for an API tutorial document: Please skim the entire template first to understand the expected structure for this type of doc. Then, clone this doc using the Clone content link in the Page tools box. Delete all content up to Introduction (this heading won't be visible).

For the doc title (the field at top of page): Doc should be named in a practical, use-case-focused way. Example: Add custom attributes to transactions

Introduction (this heading will not be visible)

Provide a brief explanation of what this document will teach customers, and why it is valuable for customers to know how to do that. Focus on the value the API provides to the customers and mention specific, common use cases.

Any relevant notes about support/compatability should go here, too.

Here's an example from the Java API asynchronous tutorial doc:

New Relic for Java includes an API to instrument asynchronous activity. For supported frameworks, the Java agent usually instruments async work automatically. However, the async API can be useful for adding more detail to your data. This document provides examples of using tokens and segments to instrument your app.

Optional: Provide an overview for complex processes

This is an optional section for complicated tutorials that involve either using several methods in one procedure or that have different alternate steps you can take to achieve similar results. This section can link to lower-down sections to allow users to skip around as needed. For simple tutorials, this section isn't necessary.

For an example, see this section of the Java async tutorial.

Provide a procedure to accomplish the task

Tell the user how to accomplish the task, and link to the methods necessary to accomplish that task. As much as possible, we're looking to describe tasks in "procedures" (procedure is tech writer jargon for a series of numbered steps). This may be tough to do for fairly open-ended/variable tasks, but it will usually be possible to chunk the content at a fairly high-level to make it into a procedure. Along the way, explain what the importance of the procedure step is, and how one might verify that the step was done correctly. For code samples, avoid using large chunks of code. Instead, use smaller pieces of code and give context for how they are being used. (If you think a large app code example would be helpful, place that later in the doc in the Example section.)

Base your procedure on the simple structure below. Tech writers will edit your content to match our style and formatting requirements:

Step 1. Do something...

Methods and example code to implement the first step.

For each step, if applicable, indicate the significance of that step (why it's important) and how the user might verify that the step was done correctly (for example, something showing up in UI, or running a verification test of some sort).

If needed: Step 2. Do something else...

Methods and example code to implement step 2.

If needed: Step 3. Do something else...

Methods and example code to implement step 3.

Last step. Verify that the task was completed...

Explain how a user would know they'd completed the task correctly. In particular, how would the user find the new change or data in the New Relic UI. What New Relic products and pages would the change be noticed on? If new data shows up in NRDB, what event types can it be found under?

Optional: Do something else with the API

Same as above. Make as many headings and separate procedures as needed.

Optional: Large example code block

If you think a large app code example would be useful, place here. Within any code block, explain all New Relic functions/methods, not just the main methods. Instead of in-line comments, consider using highlighted sections underneath the code block to give additional context. Here's an example:

private void storeItem(long id) {
   Segment segment = NewRelic.getAgent().getTransaction().startSegment("storeItem");

   segment.reportAsExternal(DatastoreParameters
           .product("H2")
           .collection(null)
           .operation("insert")
           .instance("localhost", 8080)
           .databaseName("test")
           .build());

   // fire and forget
   DB_POOL.submit(() -> {
       segment.end();
       insertData(id);
   });
}

Optional: Troubleshooting

Optional area for any common errors or troubleshooting tips.