Ask A BotHow to Write - Index Pages
This guide to writing index pages is just that—a guide. It won’t answer every question you have about how to write a good index page, but it will help you make a good start.
While we use the term “index page” to refer to the top-level page about a feature in Docs, we don’t use this terminology in the actual Docs. Learn more in Other Guidelines.
The index page:
- Explains WHAT the feature is
- Describes WHY the feature benefits the customer, without veering too far into marketing language
- Describes HOW the mechanisms of the feature help the customer achieve these benefits
- Provides easy-to-find LINKS to child pages describing the subpages of the primary feature and/or how to do things with the feature
The index page does not:
- Describe HOW TO do anything that can’t be described in one or two sentences; that information should be on child pages in Docs.
- The elevator pitch of this feature
- What the feature is and what problem it’s solving for the customer
- Two-to-five sentences
- This can be longer if you need to explain the feature as a concept before you can explain what the feature provides (for example, Releases as a feature/concept vs the Releases page of application)
- A pixel perfect overview screenshot showing the feature in action
Use this approach for a feature that doesn’t require much explanation and has distinct sections, like Usage Stats - it’s good for very contained features.
- Describe each page section/element focusing on how it helps the customer achieve the WHY of this feature.
- Add headings describing the page section/element to make each section of text stand out, if needed.
- Describe how this feature fits in/interacts with other parts of the application, if applicable (e.g., this page has a button that takes you Discover queries).
Use this approach for a page that requires more explanation to break down and/or has a lot of child pages to explain its different benefits, like Performance Monitoring.
- Describe how each page section/element or child page, helps the customer achieve the WHY of this feature.
- Include links to relevant child pages in the text.
- Group page sections/elements or child pages as appropriate.
- Add headings that describe the benefit rather than the page section/element like here.
- Describe how this feature fits in/interacts with other parts of the application, if applicable (e.g., this page has a button that takes you Discover queries).
If you use this approach, you may want to include a very high-level, one- or two-sentence description of what the page looks like as part of the WHAT/WHY section.
Create a section called “Learn More”
Use a
<PageGrid />element to link to child pages for this feature- This displays a bullet list of page links with their front matter page descriptions
- This might require that you edit the front matter descriptions of the pages displayed in the page grid
You might need to use an include file for small pieces of reusable content, such as Early Adopter notes, plan/feature notes, or short snippets of text. These are found in /includes/.
Following are some quick tips to keep in mind:
- Refer to the feature’s main page in the application as a page, home page, or even main page. Do not call it an index page or use homepage (all one word).
- Refer to the organization as Sentry; refer to the UI of the application as sentry.io (with lower case “s” and embedded link), not the Sentry UI.
- Avoid beginning sentences with sentry.io.
- Do not skip heading levels. Don’t use an H3 as your first sub-heading/page-level heading. The page title is considered the H1 and the next heading level that should be used after that is an H2. If you skip heading levels, the right hand sidebar menu won’t render.
- Do not add more H1 headings to the page. The title is the H1. All other headings on the page should be H2 or lower in hierarchy (that is, higher in number).
Internal writers, refer to the Tips for Contributors page for further guidance.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").