newrelic / docs-website Goto Github PK

Source code for @newrelic docs. We welcome pull requests and questions on our docs!

License: Other

JavaScript 0.60% Python 0.01% Shell 0.01% Dockerfile 0.01% TypeScript 0.02% MDX 99.37%

docs-website's Introduction

docs.newrelic.com

Welcome! 👋 This is the repo for docs.newrelic.com. This repo contains all the source code and Markdown source files we use to build our docs site.

Read on to learn more about who we are and how you can contribute to the New Relic Docs site.

We'd like your help

From the start, we've welcomed contributions from anyone at New Relic, not just writers. Now, we're open sourcing our docs to invite input from anyone at all. We credit our technical accuracy and comprehensive documentation to this openness.

In a sense, it's documentation as conversation. By making our docs open source, we hope to expand this conversation.

We're here working every day to improve our docs and we'd love to hear from you. Come join the conversation.

Get started

On each page of our docs, you can create an issue or edit a page.

Create an issue

Issues are a quick way to give us feedback about our docs. We'll review your issue and follow up with you if we have any questions. You can create an issue to let us know when you find an error or notice something missing. You can also let us know about things you'd like to see. Go here to create an issue.

Edit a page

If you'd like to get more directly involved, you can edit the docs yourself! Here's how:

Every doc page on docs.newrelic.com has an Edit page pencil button in the right sidebar and the footer. Click it to access GitHub and the source file for that doc page.
Make your changes, then click Commit changes. This will automatically create a fork in your GitHub account with the changes.
Finally, follow the prompts to create a pull request and submit your changes for review.

From there our writers will check out your pull request, comment with any feedback, and merge your change.

If you'd like more information on how to edit our docs, read our processes to create and edit content. Additionally, our Style guide will give you some insight into how we think about writing and documentation, as well as our flavor of Markdown. Reading the style guide is totally optional! Our writers are here to make sure everything is formatted and worded right. We're looking for your technical insight and knowhow. Let us handle the little details for you.

If you'd like to go deeper with development, see our Contributors guide for information on how to fork our site, build it locally, and submit pull requests.

🚧 Contributing

We welcome contributions to the New Relic Docs Site. Please review our Contributors Guide prior to submitting any code.

Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at [email protected].

New Relic Developer and Open Source sites

You may also be interested in the New Relic Developer website and Open Source website repos.

🏛️ Content and code license

The content of New Relic product documentation in the docs-website repository is licensed under a CC-BY-NC-SA 4.0 license.
Code, including sample code, contained in the docs-website repository is licensed under the Apache 2.0 license.
When using New Relic logos, follow New Relic’s media assets guidelines.
The docs-website project also uses source code from third-party libraries. You can find full details on which libraries are used and the terms under which they are licensed in the third-party notices document.

docs-website's People

Contributors

Stargazers

Watchers

Forkers

isaaceldridge mmfred lthelen jmiranr henrytech dralph3344 mrjameshamilton ad2joe ashleypinner tsericati ancadelmar danstadlernewrelic thezackm emilras quicksketch jemisonf linbaker cherylfrankenfield koyanod tanaka-takayoshi iharika arvdias sharonmcc superrafek courtneyphillips ckbrehm-github dustman58 harrykimpel dbetke glenofoghlu migruealt matthieumorel paologallinaharbur naxhh ejones54 kidk mlavania jodstrcil grepory tmancill joransen elmay61 cziems jasonjkeller mattwhelan josephlocascio solson2009 swati365 umaannamalai aubreyhewes bstaples gspncr morecar hroseross bridgpal lchapman4 kaznovac wrekone mmclhugo1 abhisheklad lixiong-intelex urszulae charliewinters michaelgoin angelatan2 edhjer at0s thecraic martinkuba patrick-webs danifitz jvanmetre philip-r-beckwith jaymcgrath ngsw philweber bdwyer-newrelic nr-ahemsath xixiapdx lwegener richvanderwal rkbodenner bourker-legal toobagrrl alejandrodnm jsgithub1 cleon-nr lizbaker anthonylawson robertprast iazam6 bradleycamacho dfernandeza knitterb nedl86 caitenwhite jcowan-at-newrelic pfraziernr john-withers mfb2

docs-website's Issues

[Setup] Install Husky

Summary

To help ensure that we don't push up broken or inconsistent code, we should add Husky to the project. bark bark!

Acceptance Criteria

Husky installed
lint npm script created
pre-push configured to use new lint script

Helpful Links

[Migration Research] Define JSON resources for migration

Summary

Spec out what JSON resources are required, what data needs to be in them, and how they might be used together to script sourcing of content from current docs site to .mdx files in the repo.

Procedure

Open up a PR merging into research. If there is no changes in the code (and only research details), you can just make an edit in a text file, since there is no plan to merge this into main. Use the PR template research_PR_template.md either by coping the markdown into the PR or by appending the query string ?template=research_PR_template.md to the URL. Fill out the template by answering the research questions listed below.

Research goals

Define node/content resources: endpoints, structure of returned JSON, any helpful query params
Define redirects resources: endpoint, structure of returned JSON, any helpful query params

[Migration Research] Find and evaluate solutions for migrating Markdown

Summary

In the current docs site, there are 1556 structured Markdown files for release notes (agents). We will need to transfer these over into an mdx file. In this context, structured means that in Drupal (the current CMS the docs site is using), there are several fields to define certain aspects of the pages (for example, a description field, a title field, ect).

We need to figure out a method to migrate this content into this repository into mdx files. @austin-schaefer will be determining a representative sample of documents for us to migrate over for our POC.

Procedure

Research Goals

Investigate methods of structured markdown to mdx file migration
Determine/estimate the amount of work for the implementation of each method
Determine the amount of manual work (i.e. are there any pages that we can't transfer over programmatically? why?)
Create POC for one of the methods of structured markdown to mdx file migration for the representative sample of documents

[Setup] Setup MDX to render components

Summary

Setup site to support components in .mdx files.

Acceptance criteria

As a content author, I could add an available component to an .mdx file without needing to require it in the file and it renders content.

[Misc. Research] Research and identify how long builds will take at scale

Summary

Everytime we push to Amplify, we are rebuilding our Gatsby site. In the future, when members of our docs team are editing and merging new content every few minutes, we shouldn't have to rebuild our Gatsby site fully each time. We should do some research on how long our builds take at scale and if there are ways to optimize our builds.

Procedure

Research Goals

Identify how long builds will take at scale (perform tests on our current site)
Identify possible optimizations / methods to decrease our build time

Audit the components of the Docsite and provide guidance on new components

Story

We'll want to understand what existing components are available to the Doc Site, in the shared component library and what new ones will be needed so we can look to scope and define those in another MMF.

AC

Audit the components of the Docsite / OSS site
Provide guidance and high level designs (if possible in this MMF cycle) on the new components that may need to be built for the new Docs site.
This research will be used in a future MMF to start bringing over some components from the existing Docs Site.

[Setup] Configure editor tools

Summary

To ensure code consistency, we should implement some tools like eslint and prettier. These will be enforced by some CI / git hooks (tracked in a different ticket). See "Helpful Links" section for configuration used on the developer site.

Note that no editor-specific configuration should be added.

Acceptance Criteria

babel set up and configured
eslint set up and configured
prettier set up and configured
nvm set up and configured
editorconfig set up and configured
Jest set up and configured

Helpful Links

[Build] Add clamshell/collapser components

Summary

Add components for collapser / clamshells. These should be kept basic in style/functionality for now. NR1 Help Center is a good example to draw from.

The component should not output <dl><dt></dt><dd></dd></dl> elements and instead use generic elements like <div>.

Acceptance criteria

As a content author, I can add collapsers with one or more rows that, when clicked, toggle show/hide content block.

Helpful links

Example of basic styling in NR1 Help Center > search for Dashboards

Migrate docs content planning & approach

Summary

Pulling from the IA diagram, define the steps involved in migrating content so we can be sure the content is migrated successfully.

Desired Behavior

Move APM, Browser monitoring, Logs, Understand dependencies, Infrastructure monitoring, Mobile monitoring, Serverless function monitoring, Synthetic monitoring under the FSO category
Combine "Using New Relic", "New Relic One", "Query your data", and "Mobile apps" under a new category "New Relic in Practice"
Move Infrastructure Integrations SDK to the Developer site
Move API category to the developer site. Move remaining API intro docs under the TDP category.
Remove "Open-source licensed agents" section since all agents will be made open source
Change "Enable log management in New Relic" to "Logs in context"
Append "monitoring" to the relevant categories to comply with our platform hierarchy guidelines

Possible Solution

The changes mentioned above should be reflected in the metadata for each document.
The way we represent the actual file hierarchy on disk should be flatter. Let's start with a single level of hierarchy (e.g. everything under FSO is a flat list). When this would result in ~100+ docs under a given category (e.g. release notes has 1,500+ docs), we can add a second layer of hierarchy.

Additional context

Even though we anticipate additional changes to the IA over time, moving files on disk is a bit painful, so it's important that we get the buckets roughly correct at the start. If the hierarchy is too flat, finding the right file to edit will be painful, and if the hierarchy is too deep, small changes to the IA will require a restructuring of files on disk to avoid drift.

Provide logs and list of common issues that cause build errors

NOTE: # Tech writers will need quick ways to find and fix errors that cause PRs not to merge/build. The devex team gets some of this info from Amplify. The tech docs team will either need accounts, or access to a log. It would also be great to have a list of things like white space at the start of a paragraph, or errant tags, or other format issues that are common causes so we know what to look for.

Summary

We change and publish content dozens of times a day. If we can't get those changes merged because we can't figure out what's causing an error, we're going to be a)wasting a lot of time, and b)requesting support from the devex team.

Desired Behavior

Possible Solution

Additional context

[Prototype] Add basic pages

Summary

Migrate ~10 basic page files from Drupal to the site with a representative sample of all elements/components on the site.

Acceptance criteria

Create relevant directories for each file
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

Determine how we can verify a page was migrated successfully

Description

The generalized process for migrating content from the existing site to the repository looks like this:

Fetch raw HTML
Sanitize and normalize the HTML
Create a new MDX file
Add frontmatter details for the page
Add the HTML content from step 2
Verify the page is working correctly

In order to complete the process, we need to verify the page is working correctly. When we run npm run build on our machines (or the code builds on Amplify) Gatsby will return an error if a page is not working correctly. We can probably use this to identify if a page is not building. That said, we need a way to identify all the pages that have issues, not just the first one before the build quits.

If there's 1 page broken, we fix the page. If there are 100s of pages broken, we need to fix the migration code. Knowing the number of pages (and which pages) are broken is critical.

Related Issue(s)

After reviewing the remaining research tasks, we have decided to break the work in #12 down into multiple smaller tickets. This is one of those tickets.

Success Criteria

Determine how we verify if a page is broken (is npm run build output sufficient)
Identify how we can get a list of pages that are not working post-migration

[Migration Research] Find and evaluate solutions for migrating Redirects

Summary

In the current docs site, there are over 5,550 redirects from old pages to current docs content. We need to figure out methods for handling these redirects, whether it be through Gatsby, Amplify, or some other technology. Currently, the redirects are listed out in Drupal (the CMS the docs site uses) as referring to other node numbers which represents pages. We need to figure out how to match the redirects from the nodes to the URLs and then configure the redirects.

Procedure

Research Goals

Investigate methods of transferring the redirects
Determine/estimate the amount of work for the implementation of each method
Create POC for one of the methods

[Prototype] Add release notes (platform) pages

Summary

Migrate ~5 release notes (platform) page files to the site with a representative sample of all elements/components on the site.

Acceptance criteria

Create relevant directories for each file
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

[Prototype] Initial PoC to automate content migration

Summary

Build initial PoC of a script that reads JSON and creates .mdx files that match format of other files of same content type that were created in this MMF. In other words, see if you can programmatically create the files.

Acceptance criteria

Review findings / PR for #42
Review findings / PR for #43
Create separate repo for script or put it somewhere where others can access/use it?
Create a script that reads representative sample of JSON data, creates an mdx file in the appropriate directory structure, sets frontmatter based on content type, processes source (likely HTML) to either ensure it works in .mdx OR converts it to markdown.
Ensure pages are successfully created upon develop and build.

Helpful links

May be helpful to look at a doc I put together as a checklist of things to look out for when rendering docs content in external apps / projects.

Add Docs content type templates

Summary

In Drupal, there are several templates that we use to guide people (both on our team and outside of it) in writing specific types of content. (You can see most (all?) of them here: https://docs.newrelic.com/node/add)

For example, the Troubleshooting template has specific fields for Problem and Solution and Cause. What's New (or NR1 Announcement) has specific fields for including Learn more and Get started links.

We were wondering if these templates were being discussed and, if not, we wanted to raise awareness about them.

We were thinking it might be great to have some kind of CLI tool to generate blank Docs templates. Maybe there's even some more elegant solution we haven't thought of!

The current templated content types are:

Add basic page
- Use basic pages for most documentation.
Add article
- Use articles for time-sensitive content like news, press releases or blog posts.
Add book page
- Books have a built-in hierarchical navigation. Use for handbooks or tutorials.
Add release notes
- This is an article type with additional fields for release notes.
API doc
- This content type is used to document API calls in a given category (for example, PHP agent API). Each method has its own front-end page and the menu page displays a specially formatted page with all the calls. https://newrelic.atlassian.net/browse/DOC-2653
Attribute Definition
- This content type is for New Relic event attribute definitions. This content is displayed on the site and is consumed by the Insights team and displayed in the UI as the attribute dictionary service. For full details see https://newrelic.atlassian.net/browse/DOCCMS-92
Automated release notes
- This content type is for auto-generated release notes.
NR1 Announcement
- For content exposed via API to PLG What's New content. https://newrelic.atlassian.net/browse/DOCCMS-274
Platform Release Notes
- For SaaS-based release notes. For full details, see https://newrelic.atlassian.net/browse/DOC-3815
Troubleshooting Doc
- This content type is used to document troubleshooting information. https://newrelic.atlassian.net/browse/DOC-3398
Webform
- Create a new form or questionnaire accessible to users. Submission results and statistics are recorded and accessible to privileged users.

Desired Behavior

According to @roadlittledawn:

"some fields in the various content types are authored in HTML, which isn’t really supported / intended to be in frontmatter. so those fields will likely all have to be combined into the markdown file body. example: the problem, solution, cause fields for the troubleshooting_doc content type.
other fields (like categories, timestamps, links, etc), will be migrated and stored as frontmatter.
i like the idea of a simple script you could run to create a template for each content type, or some such tooling."

I think, ideally, we'd have a simple CLI script that we could run to generate a mostly MDX file with frontmatter and Markdown body text pre-populated. It would be nice to include Notes and Tips for writing templated content (sort of like this enhancement request).

Possible Solution

I don't really know the publishing process well enough to suggest a possible solution and there may be Gatsby features and functionality that I'm not aware of too.

Additional context

Without standard templates for content, we run the risk of having writers reinvent the wheel or create content that veers of slightly from what we expect to see in our templated content.

[Migration Research] Find and evaluate solutions for migrating Plain Text

Summary

In the current docs site, there are 2221 structured plaintext files for attribute definitions. We will need to transfer these over into an mdx file. In this context, structured means that in Drupal there are several fields to define certain aspects of the pages (for example, a description field, a title field, ect).

Procedure

Research Goals

Investigate methods of plaintext to mdx file migration
Determine/estimate the amount of work for the implementation of each method
Determine the amount of manual work (i.e. are there any pages that we can't transfer over programmatically? why?)
Create POC for one of the methods of plaintext to mdx file migration for the representative sample of documents

Localization Pre-MMF research

As we migrate the docs site to gatsby we need to define our approach for localization for the new site. This task is to do some preliminary investigation into how we will approach localization short term and long term.

Short Term

Evaluate the current technology approach with the Drupal site to see if there is a way to use the existing vendor solution for our localization approach with the new site.

Long Term

Evaluate the long term technology approach and determine an iterative way to move forward.

[Convert] Add codemod to migrate source to Video component

Summary

Add codemod to migration script that converts videos to Video components. The current site almost entirely uses <p><iframe></p> elements that use wistia videos.

There's only 1 youtube video on current site, which is also in an <iframe>.

Acceptance criteria

As a developer, I can run the migration script and any Wistia / Youtube <iframe> elements are converted to the Video component.

Helpful links

Wistia Example: Kubernetes video
Youtube Example

Please add Tessen instrumentation for stitched path buttons

newrelic/developer-website#352 # Is your feature request related to a problem? Please describe

The documentation team is trying to track customer usage of buttons on the Drupal doc site that take users into installation assistants within the product. To do this, we'd like to request some Tessen instrumentation that captures when users click these buttons.

We're not sure if the solution applies to all pages in the docs site, or whether it will require the instrumentation of every page that contains these special buttons. Here are some links to pages that have these buttons (but there are more):

Describe the solution you'd like

We would like a Tessen event generated when users click on these buttons.

Describe why this important to you

We hope this will help us assess the effectiveness of these buttons for driving users to the installation assistants.

[Prototype] Develop basic template for all .mdx files

Summary

Once we have .mdx files in place, we need a template to create the front-end view of the content. For now, just want to keep it to one, very basic template.

Acceptance criteria

Create a basic template in src/templates that renders mdx.frontmatter.title, and mdx.body (main body of file)
Update .mdx files as needed to reference the template name

Helpful links

Example GuideTemplate on developer site

[Prototype] Add troubleshooting pages

Summary

Migrate ~5 troubleshooting page files to the site with a representative sample of all elements/components on the site.

Acceptance criteria

Create relevant directories for each file
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

[Setup] Add filesystem sourcing & MDX

Summary

Set up Gatsby to source content from a .mdx files in the repo to generate static HTML pages.

Acceptance criteria

Install gatsby-source-filesystem plugin
Install gatsby-plugin-mdx plugin
Configure image directory (gatsby-config.js). This may already be configured via gatsby-theme-newrelic
Configure content directory/directories (gatsby-config.js)

Helpful links

Identify what frontmatter fields we should support for each content type

Description

There are 6 different content types in the Drupal site (soon to be 7). Each content-type has it's own collection of fields representing metadata for the page. In theory, we could turn each set of fields into a set of frontmatter and have each content-type use it's own template in Gatsby. That said, there may be room for some simplification. For example, some of the content types' fields could simply be content in the markdown file itself.

The purpose of this ticket is to create a proposal for how each content type could be handled in MDX. If we could develop an example MDX file for each demonstrating how a page could look after a migration, that would be helpful. It's possible that (and maybe even ideal if) multiple content types will use the same frontmatter fields and template.

Related Issue(s)

After reviewing the remaining research tasks, we have decided to break the work in #12 down into multiple smaller tickets. This is one of those tickets.

Success Criteria

Create an example MDX file (including frontmatter) for a:

"basic page"
"troubleshooting page" (if applicable)
"agent release note" (if applicable)
"platform release note" (if applicable)
"attribute definition" (if applicable)
"agent API" (if applicable)
"what's new page" (if applicable)

Determine where markdown files will reside within the repository

Description

In order to migrate content from the existing site to the new repository, we need to know where each page's markdown file will live within the repository. The original developer proposal was to have a directory structure that mimics the page's category. A page with this category structure foo > bar > page would be stored a directory like src/md/foo/bar/page.mdx.

Before we start the migration work, we need to confirm that this will work. If another structure is preferred, we should document that here to help inform the upcoming engineering work.

Related Issue(s)

After reviewing the remaining research tasks, we have decided to break the work in #12 down into multiple smaller tickets. This is one of those tickets.

The developer proposal for this has been identified in #11. This ticket is to track that we still have an open decision to be made.

Success Criteria

Come to a consensus with engineering, PM, design, and other stakeholders for a first-pass solution to where we store content within the repository

Obtain stakeholder reviews and feedback on the current IA approach for this site.

Obtain stakeholder reviews and feedback on the current IA approach for this site. If possible, obtain stakeholder sign off on IA approach.

Finalize What's New on current site

This is to track any remaining work related to supporting PLG's What's New / nr1-announcements content type on current site. This was work that began in March and was paused in May-ish. Most work is done, but remaining items include:

tweak template/view for What's New content on docs site
add JSON resource to support showing that content in NR1 Help Center
ensure moderation workflow rules are as set

[Prototype] Create a framework for transforming migrated content

Summary

We may discover issues with the HTML when migrating the content from the existing docs site to MDX. Furthermore, there may be HTML snippets we need to convert from one format to another. We need to create the tools and the framework for generating codemods that we can run on all the MDX files.

Acceptance criteria

Can run a codemod on an MDX file and transform it
Allow others to create custom codemods that can transform content in some way

[Setup] Create staging environment in Amplify

Summary

In addition to having a production environment set up in Amplify, we should also have a staging environment (that is password protected). For an example of how to configure this, check out the opensource website setup.

Acceptance Criteria

New environment set up in Amplify
Amplify set up to build to staging environment with new merges to develop
Password protection set up in Amplify
Link (and credentials) shared with team (pin in slack?)

Helpful Links

[Setup] Set up project in Amplify

[Setup] Create / Update README

Summary

This repository was automatically generated and we need to update the README with relevant information.

Acceptance Criteria

Project name and brief description
Installation and getting started (including dependencies)
Support link

Helpful Links

Developer Website README

[Prototype] Add attribute definitions

Summary

Migrate ~5 attribute definition files to the site.

Acceptance criteria

Create relevant directories for each file. These should go in their directory separate from other content types.
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

What adjustments needed to be made to raw HTML when migrating to MDX?

Description

During the migration process, we will have access to the raw HTML that represents a page. Whether we get this from a JSON output or from MySQL, we will need to process the HTML content before we can add it to a .mdx file.

During our initial research, we copied HTML for a page into a .mdx file in the dev site repository as a simple test. It became clear that some adjustments needed to be made before Gatsby could properly serve the page. Some of the initial findings include:

Specific elements (such as the dl tag) have requirements for how they are being indented
Special characters (i.e. { and }) need to be escaped or removed.

We should take some time to identify the most common adjustments / santization steps. The goal is to have a list of functions we will need to implement in the engineering stage and to uncover any potential issues before we get started developing.

Related Issue(s)

After reviewing the remaining research tasks, we have decided to break the work in #12 down into multiple smaller tickets. This is one of those tickets.

Success Criteria

Create a list of adjustments that need to be made to raw HTML documents
Document findings in this issue so that they can be used to inform the automation code (upcoming MMF)

[IA Research] Determine directory structure for content

Summary

There are over 5,000 markdown files that will be in the documentation site. We need to figure out a way to structure this content in our repository.

Procedure

Research Goals

Determine a file structure for content (is it determined by folder, by frontmatter ect.)
Discuss solutions with engineers, content creators and PMs to determine best path forward

[Build] Add table component

Summary

Add components to support tables with some basic options.

There's two main types of tables used on current site: standard table and spec table (no column headings, small fixed width, used primary for config settings). And I believe many tables have in-line style to specify column widths.

Nice to have props to support:

every other row background coloring
highlight row on hover
flexible layout (user can optionally specify column widths, entire table width)

Primary reason for building out this component is tables are not fun to author in markdown :( And this makes it easier to add some more interactive features. Also, there are typically other elements nested within table cells like callouts, ordered/unordered lists, etc)

Acceptance criteria

As a content author, I can add a standard table without specifying any options
As a content author, I can add a table and specify the table width and column widths
As a developer, I can use same component when converting either standard or spec tables by specifying necessary table/column widths

Helpful links

Example: Complex table
Example: Standard table w/alternate rows
Example: Standard table w/ul
Example: spec tables in .NET config
Maybe use NR1 component as model? Developer: NR1 Table component for inspiration

[Prototype] Add directory landing pages

Summary

Migrate ~3 directory landing page files to the site with a representative sample of all elements/components on the site. Directory / Category landing pages are pieces of authored content that site at the category/directory level in the nav.

Acceptance criteria

Find/Add top level directories to add index.mdx files, that ideally match docs site landing pages (consult Daniel's IA graph for ideas or list of docs links below)
Copy HTML from Drupal into the .mdx file
Add frontmatter similar to example file. It can probably use the basic template that's set up as part of this MMF in another ticket.
Ensure pages are successfully created on develop and build

Helpful links

Docs IA

Landing page examples
https://docs.newrelic.com/docs/browser
https://docs.newrelic.com/docs/infrastructure
https://docs.newrelic.com/docs/synthetics

[Setup] Configure repository

Summary

Ensure that we have the correct configuration for our repository.

Acceptance Criteria

Repository created
main branch created
develop (or similarly named) branch created and set to the default
Branch protection set up on main and develop
OPENSOURCE_BOT_TOKEN secret for future use
Contributors updated and approved

Helpful Links

N/A

[Build] Add heading component

Summary

Add heading component that supports specifying the level and ID attribute.

The ID attribute is important when users share links to specific sections of the site and for use by the On this Page ToC.

Currently, content authors primarily only use <h2> and <h3> headings, though I found at least two pages that use <h4>.

Acceptance criteria

As a content author, I can add either a heading 2 or 3 element and optionally specify the ID attribute
The ID attribute is automatically generated via a slug of the text of the element

Helpful links

Example: many h2 and h3
Example: h4 inside collapser

[Setup] Set up project in Amplify

Summary

The new docs site will be hosted using AWS Amplify.

Acceptance Criteria

New project created in Amplify
amplify.yml added and configured
Amplify set up to build with new merges to main
Preview builds set up
Team members all have access to Amplify dashboard

Helpful Links

[Setup] Install Gatsby & New Relic Theme

Summary

The new docs site will be built using Gatsbyjs and will utilize the New Relic Gatsby Theme. This ticket represents the work needed to add those to the project and configure them.

Acceptance Criteria

Gatsby installed
Theme installed
Theme configured for the docs site
Set up browser agent

Helpful Links

[Prototype] Add release notes (agents) pages

Summary

Migrate ~5 release notes (agents) page files to the site with a representative sample of all elements/components on the site.

Acceptance criteria

Create relevant directories for each file
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

[Migration Research] Find and evaluate solutions for migrating HTML docs

Summary

In the current docs site, there are

1599 Basic pages (HTML, unstructured)
144 API docs (HTML, semi-structured)
143 Trouble shooting docs (HTML, semi-structured)

Procedure

Research Goals

Investigate methods of HTML to mdx file migration
Determine/estimate the amount of work for the implementation of each method
Determine the amount of manual work (i.e. are there any pages that we can't transfer over programmatically? why?)
Create POC for one of the methods of HTML to mdx file migration for the representative sample of documents

[Misc. Research] Find and evaluate solutions for hosting images / assets

Summary

There are ~3,000 images currently in Drupal for the docs site. There are some engineering challenges that are going to come with these images. One is that we will likely not want to hold all of our images in our repository, so we have to find and evaluate solutions for hosting images.

Procedure

Research Goals

Evaluate solutions for extracting the images
Evaluate solutions for hosting the images
Discuss solutions with engineers, content creators and PMs to determine best path forward

[Convert] Add codemod to migrate source to Caution callout component

Summary

Add codemod to migration script that converts caution callouts in source to the Caution component.

Callouts on the current site are <div> elements with a class that specifies the type of callout.

All callouts used on current docs site include the following.

Acceptance criteria

As a developer, I can run the migration script and any caution callout elements are converted to the Caution component.

Helpful links

Example: Caution callout
Style guide doc on callouts (requires logging in)

[Prototype] Add What’s New / NR1 announcement

Summary

Manually add the sample What's New / NR1 Announcement file to the site.

Acceptance criteria

Create relevant directories for each file. I think these should go in their own directory separate from other content types.
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

[Prototype] Add API doc pages

Summary

Migrate ~5 API doc pages files to the site.

Acceptance criteria

Create relevant directories for each file
Copy HTML from Drupal into the .mdx file
Add frontmatter based on example file and relevant field values in Drupal
Ensure pages are successfully created on develop and build

Helpful links

[Prototype] Add auto-generated directory index pages

Summary

Automatically generate directory index pages for directories that do not already have an authored index.mdx (landing page) that are super basic, roughly similar to existing index pages.

Acceptance criteria

In gatsby-node.js, map relationship for mdx files to directories, directories to other directories
Create template to handle the data you pass to it and render content (likely need to use a different template than the basic one created to display other .mdx files)

Helpful links

Docs IA
Example from my prototype

Directory index page examples
https://docs.newrelic.com/docs/synthetics?toc=true
https://docs.newrelic.com/docs/agents/php-agent/getting-started

[Migration Research] Research how internal links will be handled post-migration

Summary

Another consideration of redirects / links is looking at internal links in the pages. We're going to need to find a way to redirect internal links to the correct pages, as well as determine if there are any broken links within the content of the pages.

Procedure

Research Goals

Investigate methods of parsing internal links
Investigate methods of testing for broken links within a site

[Build] Add ordered list components

Summary

Add a component for ordered lists, a very common element on the site for procedural content.

Primary reason to add this is to support nesting content more easily. And eventually may want to do something special with numbering format, etc.

Common elements nested inside ordered lists are: callouts, codeblocks, images, example boxes, clamshells.

Acceptance criteria

As a content author, I can add ordered list components that have text or other nested elements/components

Helpful links

[IA Research] Identify a solution for categories

Summary

Currently there is a three category (layer) structure reflected in the doc URL, we want to recreate this for the current docs site but we want the flexibility to not be locked into this structure.

Procedure

Research Goals

Investigate solutions for the taxonomy (categories) that can be reflected in the URL
Discuss solutions with engineers, content creators and PMs to determine best path forward

[Setup] Create initial JSON resources

Summary

Create initial set of JSON resources in Drupal the team can look at, test against.

Acceptance criteria

Review findings/PR for issue 42
Set up node/content JSON resources
Store small subset / document how to access / use them