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
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.
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.
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:
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).
Methods and example code to implement step 2.
Methods and example code to implement step 3.
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 NR products and pages would the change be noticed on? If new data shows up in Insights, what event types can it be found under?
Same as above. Make as many headings and separate procedures as needed.
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:
Optional area for any common errors or troubleshooting tips.
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's data security and licenses documentation.