newrelic / docs-website Goto Github PK
View Code? Open in Web Editor NEWSource code for @newrelic docs. We welcome pull requests and questions on our docs!
Home Page: https://docs.newrelic.com
License: Other
Source code for @newrelic docs. We welcome pull requests and questions on our docs!
Home Page: https://docs.newrelic.com
License: Other
Migrate ~5 attribute definition files to the site.
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>
.
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.
develop
Pulling from the IA diagram, define the steps involved in migrating content so we can be sure the content is migrated successfully.
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.
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.
The new docs site will be hosted using AWS Amplify.
amplify.yml
added and configuredmain
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:
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)
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
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.
Landing page examples
https://docs.newrelic.com/docs/browser
https://docs.newrelic.com/docs/infrastructure
https://docs.newrelic.com/docs/synthetics
Migrate ~5 troubleshooting page files to the site with a representative sample of all elements/components on the site.
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>
.
Example of basic styling in NR1 Help Center > search for Dashboards
Manually add the sample What's New / NR1 Announcement file to the site.
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.
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.
src/templates
that renders mdx.frontmatter.title
, and mdx.body
(main body of file)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.
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.
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.
Obtain stakeholder reviews and feedback on the current IA approach for this site. If possible, obtain stakeholder sign off on IA approach.
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:
Create initial set of JSON resources in Drupal the team can look at, test against.
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.
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.
This repository was automatically generated and we need to update the README with relevant information.
The generalized process for migrating content from the existing site to the repository looks like this:
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.
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.
npm run build
output sufficient)Migrate ~5 release notes (agents) page files to the site with a representative sample of all elements/components on the site.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
Example: Caution callout
Style guide doc on callouts (requires logging in)
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.
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.
Ensure that we have the correct configuration for our repository.
main
branch createddevelop
(or similarly named) branch created and set to the defaultmain
and develop
OPENSOURCE_BOT_TOKEN
secret for future useN/A
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.
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.
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.
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.
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.
Create an example MDX file (including frontmatter) for a:
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.
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.
To help ensure that we don't push up broken or inconsistent code, we should add Husky to the project. bark bark!
lint
npm script createdpre-push
configured to use new lint scriptIn 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:
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).
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.
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.
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.
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.
Setup site to support components in .mdx files.
require
it in the file and it renders content.Migrate ~5 release notes (platform) page files to the site with a representative sample of all elements/components on the site.
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):
We would like a Tessen event generated when users click on these buttons.
We hope this will help us assess the effectiveness of these buttons for driving users to the installation assistants.
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.
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.
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>
.
In the current docs site, there are
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.
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.
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.
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.
Migrate ~10 basic page files from Drupal to the site with a representative sample of all elements/components on the site.
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.
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
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.
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.
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:
dl
tag) have requirements for how they are being indented{
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.
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.
Set up Gatsby to source content from a .mdx
files in the repo to generate static HTML pages.
gatsby-source-filesystem
plugingatsby-plugin-mdx
pluginMigrate ~5 API doc pages files to the site.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.