How to write NerdGraph docs

This resource contains style guide recommendations and guidelines for writing about New Relic's NerdGraph API.

Style-related guidelines

Some style-related guidelines when writing about NerdGraph:

• NerdGraph. You should refer to it in general as "NerdGraph" or "New Relic's NerdGraph." On first mention, it's acceptable to phrase it as our "NerdGraph API," especially in contexts where it may not be immediately obvious that we're talking about an API.
• NerdGraph is a single API. NerdGraph is not a set of different APIs. There is sometimes an inclination to refer to NerdGraph as a collection of APIs, which is actually somewhat true because NerdGraph does pull together a lot of our APIs under the hood, but from a customer point of view, we want to refer to it as a single API. For example, instead of saying something like, "use NerdGraph's entity API" we might say something like "use NerdGraph to view and configure your monitored entities."
• GraphQL. GraphQL is the open-source API format that NerdGraph was built with. It is okay to occasionally highlight this when appropriate because GraphQL is well known in the tech world and some people are already familiar with how it works.
• NerdGraph explorer. We mainly refer to this as "the NerdGraph explorer" or "our NerdGraph explorer" but if it's in a context where it may not be obvious what exactly NerdGraph is, you can refer to the "NerdGraph API explorer." Other tips:
  • Because there is a different URL for the EU version of the NerdGraph explorer, we should generally link to the NerdGraph explorer docs section and not to the explorer URL.
  • Avoid using just "explorer" because that conflicts with other explorers (for example, the REST API explorer, or the entity explorer).
  • We can explain, if we think it's helpful, that the NerdGraph explorer is built with GraphiQL, an open source platform for building GraphQL queries. This may be helpful to explain because both GraphQL and GraphiQL are known in the industry.
• Requests. There are two main types of GraphQL operations: queries and mutations (defined here). We can use these terms to refer to specific examples (for example: "here's a mutation that..."). To make a general reference to multiple NerdGraph requests of different kinds, you can use "requests."
• Fields. Fields are the elements on an object type that can be queried. For examples of "field" being used in context, see this NerdGraph tutorial. The reason fields are an important concept is that with GraphQL-format APIs, users specify exactly the fields they want back (in contract to REST APIs, for example, which can return a default response with fields you don't need).

Tips for creating NerdGraph documentation

It's okay to add relatively small sections of NerdGraph-related content to docs that aren't in the NerdGraph docs category. As a rough guideline, if it's more than a page of NerdGraph-related content, you should attempt to add it to the NerdGraph docs category (either in its own doc or in a related doc, if possible).

If you're adding content to the NerdGraph docs category, consider the following tips for helping keep our content efficiently organized and easy to find:

• Consider adding content to an existing tutorial. When adding new NerdGraph content, check to see if you can include new content in existing NerdGraph docs. This helps us keep the list of tutorials clean and prevent it from sprawling. For example, if you want to add something related to viewing or configuring entities, you might add that to the entity-related NerdGraph doc.
• Choose a doc to emulate. When writing a new NerdGraph tutorial doc, you can use this NerdGraph doc as a rough template. Feel free to change this structure based on whatever you or the SMEs think is needed to help customers understand the API functionality, but that general structure should work for many docs.
• When you add a new type of NerdGraph content, add it to the index of NerdGraph content. That index was created to reflect that we have tutorials available that aren't in the main NerdGraph docs section.

Some tips when writing NerdGraph content:

• Example requests. Tips for creating example requests:
  • Use tags for customer-specific values in example queries and mutations. Remember that you don't need to use tags in example responses or error messages.
  • It's good practice to explain the general use of a request, followed by a note that the example request is just an example (as opposed to communicating that it's the only way to accomplish something). So for example, you might say, "You can use NerdGraph to update your API test synthetic monitor. Here's an example of creating an API test monitor that...".
  • To clean up the format of a request, go into NerdGraph explorer and input the request and click Tools > Prettify. Note that the request must be a working one, with real values.
• Field definitions. The NerdGraph explorer includes built-in field definitions, but it can be good to explain any of the more complex or non-obvious fields in your doc. For common fields used in all or most of the example requests, one way to tackle this is with an "Important concepts" section near the top of the doc, in which you include any recommended reading or notes on important fields. For fields that are only used in one or two requests, you may prefer to explain them when introducing the example request.

NerdGraph schema documentation

The NerdGraph explorer exposes NerdGraph schema definitions to help users understand what the various fields are. The docs team reviews the schema docs that are submitted by engineering teams. For more on how schema definition review happens, see the docs team's resource 'External documentation repos.'