These are guidelines that will help us achieve more consistent and less redundant documentation when product teams add new UI pages or UI components.
Purpose of guidelines
New Relic product teams occasionally release new UI components, or even entire UI pages. Having guidelines for how to approach these UI additions will help the docs team:
- Avoiding over-documentation and redundancy, which makes docs harder for customers to read and makes maintenance harder (see examples of overdocumentation)
- Avoid inconsistency in docs (very in-depth docs versus minimal docs)
- Give guidance to other teams on how to create docs drafts
Guidelines
Here are some simple guidelines for approaching requests to document new UI components or pages:
- Our default philosophy is to not document, unless we see a good reason to document.
- Avoid documenting things that seem obvious or intuitive.
- Avoid redundantly documenting aspects of a feature that are present in multiple places in the UI.
- When we can, try to fit UI instructions in a how-to or tutorial-type approach, as opposed to a UI reference approach.
Regarding that last point, here are differences between a reference approach and a tutorial approach:
- Reference: a 1:1 explanation of components in the UI (for example, most of this infrastructure UI doc takes a reference approach). We believe this approach is not engaging and therefore is less likely to be read by customers.
- Tutorial: instructions for achieving specific goals and use cases. We believe this approach is more helpful and likely to be used.
Here are some more details on these guidelines.
Default approach: no documentation
Our default philosophy is to not document, unless we see good reasons to document.
Another way to put this is that the release of a new UI component or new UI page does not necessarily require us to document it, unless we think there is something important and helpful to say about it. We should avoid the instinct or pressure to think: "They made it and therefore I need to find something to say about it." That pressure to create documentation is what leads to over-documentation and redundant documentation.
For example, sometimes product teams add or edit charts that are present in curated views (like the infrastructure UI or the APM UI). We don't include documentation on every curated New Relic view, and we may decide that the updates speak for themselves and don't require us to document anything.
For another example: if a new UI component helps customers with a specific procedure or use case, we may decide to only mention that UI component in the context of a specific procedure or tutorial, as opposed to documenting it in a dedicated UI reference doc.
Usually, there will be something we think is worth documenting about a new UI component, but not always. Having a default of "no documentation" helps us formalize our goal of concise and efficient documentation.
Avoid documenting the obvious or intuitive
If new UI includes features that are common in many UI experiences and therefore rather intuitive, you should avoid documenting those. And, relatedly, you should try to document what is not obvious about using a UI experience. Taking this approach will help you arrive at the most succinct and helpful documentation.
For example, many UI experiences for many applications include CRUD functionality (create, read, update, delete). Much of this functionality will be straightforward to anyone who has used any software, and this means we can avoid belaboring these more intuitive aspects of our product (and focus on the less obvious and more helpful aspects). For an example of avoiding documenting obvious UI functionality, see Example of minimal docs: Lookup table.
Avoid documenting New Relic features that are documented elsewhere
We should avoid creating redundant documentation, as a general rule, because having redundant docs can make maintenance and updates much harder.
If we find ourselves writing about a feature that's available in other New Relic UI experiences and/or documented elsewhere in the docs, we should either not mention it or, if we think it's helpful to mention it, link to the existing docs for more detail.
If we notice a general platform feature that we don't currently document that we think should be, we should try to add that somewhere in the Learn about the platform section of docs (as opposed to shoehorning it in a fairly unrelated doc).
Some small amount of redundancy can be okay, if we think it's helpful and if it's very short. For example, we sometimes mention specific attributes or config options that are helpful for specific contexts in more than one doc. But for anything above a couple sentences, we should try to avoid redundancy.
Examples of documentation approaches
Here are some examples of approaches taken for different types of UI components and pages. Our featuring these examples doesn't mean that we think these docs are perfect, or must be emulated. We include them to give you some ideas for how to approach different types of projects.
Example of minimal docs: Sign-in using Google
We had a request to document Google authentication: the ability to create a New Relic account with a Google account, and sign in using that Google account. The initial request was several paragraphs long, including details about how the implementation worked and how different situations were handled.
Upon reviewing, we found that the account creation and login process was intuitive and obvious, and that any customer-facing problems that arose were handled with error messages and instructions in the UI itself. For that reason, it was decided we didn't need that information in the docs: that including such things in the docs would be redundant and also potentially confuse customers with too much detail.
You can see the brief mention of Google authentication in the Login options doc.
Example of minimal documentation: Lookup table UI
The initial draft for the lookup table UI docs included several pages of detail about how a New Relic user could create, update, and delete a lookup table. But because most of that CRUD (create, read, update, delete) functionality was intuitive and expected, we removed almost all of that content. We instead basically communicated, "Here's where you can create and manage your lookup tables" and then included some helpful, non-obvious tips for using that UI. See the lookup table docs.
Example of focusing on tasks: User management
One way to document the UI is to focus on tasks and use cases, instead of taking a UI reference approach of explaining what each part in the UI does. This user management doc is an example of focusing on some common tasks that can be accomplished on a UI page.
You can also combine use cases with more reference-type material. In this infrastructure UI doc, we give an example use case before the more reference-type docs.
Example of in-depth docs for a UI page: APM summary page
Some UI pages we have minimal or even no documentation about, but the more important the UI page is, the more likely we are to document how to use it.
The APM summary page doc goes into detail about how to make use of that UI page. Note that it is focused on a specific use case, and tries to focus on how a customer would use it, instead of simply a reference of what each part does.
Example of in-depth docs for a UI page: Distributed tracing
Some UI components are harder to understand than others. This is true for the distributed tracing UI. For that doc, we attempted to explain the most important and basic information towards the top of the doc, and then put the more detailed, technical information in collapsers at the bottom of the doc. Those “footnotes” can then be referenced in other places in the docs for when we need to give more technical detail about various aspects of that UI works.
Examples of over-documented and redundant docs
These collapsers provide examples of excessive and unnecessary documentation: