UI installation guidelines

If you're reviewing or composing UI installation routines based on YAML files, follow these tips to keep your documents consistent and to streamline your work. You'll find both general principles and specific recomendations.

General principles

Writing these installation routines requires even more concise writing than general documentation on the main documentation site. Use these guidelines to help you keep your writing as streamlined as possible:

• First guiding principle: We want users to be able to complete the installation process within the UI, without the docs or other external resources. In some cases, you'll encounter exceptions to this and have to link to third-party documentation because it is required for completion.
• Second guiding principle: Less is more. Deletion should be your first impulse.

Heading information from data source file

At the very top of the installation stages and content pages is a description that comes from either the internal data source files or the community files.

This is often generic content that could use some improvement. To change these descriptions, make a pull request in the appropriate repository.

Use this format as a guide to help us keep the descriptions somewhat consistent:

With our [INSERT_NAME_HERE] integration you can [INSERT_ACTION]. See your [INSERT_DATA_TO_BE_MONITORED]

Here's an example for Lighttpd:

With our Lighttpd integration you can monitor the performance of your web server. See your uptime, network in bytes and packets, number of connections, and more.

Introductory information

Do not create introductory stages since users almost always know why they are interested in their choice of technology. For example, if you are migrating instructions from our docs site into the UI, leave out background and use-case material.

You can insert minimal introductory information into the heading, which is stored in the data source file. Keep in mind that you can't format the heading with Markdown, so keep it simple.

If you must include some additional introductory material, insert it into another stage as supporting information.

Stages

Stages carry the user through the installations with specific steps they need to complete.

Stage labels

In the left margin showing the stage steps, choose an active verb for the first word in the label. This helps users see the actions they need to take. For example, use active words like Edit and Run:

• Edit the configuration file
• Run the curl command

Repeat the stage labels as the first heading in the body:

Stage content

For the stage content:

• Begin each stage with the default action or most common installation path and focus on that.
• Break different environments into tabs or selectors, trying to present buttons for users at an early stage (for example in the flow stage).
• Only insert external links that are essential to the setup.
• If a document you are converting has links to essential content that we own, bring it into the stages where possible.
• Minimize your use of optional material, but if you need to include it, move it to the bottom of each stage.

Requirements

When you're documenting requirements, here are some ways to reduce the friction for users:

• If the requirements are complex, create a separate stage called Review requirements.
• If the requirements are minimal, leave them out. If these minimal requirements are absolutely necessary, insert them into another stage, such as installation.
• If you need a separate requirements section, use text like We support most frameworks. We don't support [INSERT_EXCEPTIONS].
• Do not treat the infrastructure installation as a prerequisite—make it a complete stage.
• Avoid including any optional content (this includes optional configurations or products like Infinite Tracing).

Lists

The framework supports ordered (numbered) and unordered lists (bulleted lists).

Ordered lists

Use these two tips to keep your ordered lists concise:

• Ordered lists are procedures that need to contain all the relevant information for each step—avoid linking to other documents from your steps.
• Numbered lists should start with active verbs in the steps.
• If you have more than four steps, you may need to divide them into different stages.

The installation framework supports two types of ordered lists:

• Blue-circled numbered lists (created in YAML by steps:)
  • Use these for primary steps.
  • Nest any Markdown lists below them.
  • You can't insert any formatting in these list types.
• Ordered Markdown lists: Use these as child lists below blue-circled ordered lists.

Unordered lists

Although the framework supports Markdown unordered lists, avoid using them.

• If you think you need bulleted lists, they're probably optional and can be deleted.
• Consider converting them into steps that you want someone to complete. If you can't do this, they're probably optional and can be deleted.

View your data

The final stage of your installation routine tells users how to see their data.

• Make sure every install framework includes a separate See your data stage.
• Standardize the stage name with See your [INSERT_NAME] data. If the product name is too cumbersome, default to See your data which follows the same naming convention as the button.
• Repeat the stage name as the title in the main body.
• Don't include any links to other sites or supporting information—only display the See your data button. This may mean you need to skip other helpful information such as NRQL queries to find data.
• Don't include any text in this stage unless it is necessary to reduce ambiguity.