Technical writers play an important role in the publication of "What's new" posts. While our contributors follow Instructions to create What's New posts, you will take some additional steps to help contributors finalize their work.
An overview of the process
A high-altitude view of the What's new process looks like this:
- Anyone in the company can submit a
What's newpull request (PR) to the docs website. - A number of product marketing managers are on rotation to review posts and make suggestions.
- When the product marketing manager finishes reviewing the post, they insert a PR comment asking tech docs to do another review.
- The tech writer completes the review and either publishes the post, or puts a comment in the PR confirming that it's ready to be posted on a certain date and time window.
Specific tech writer tasks for posts
Each day, the hero is responsible for checking the status of What’s new posts. The daily hero takes ownership of the post (reviewing, posting, and confirming that posts make it to docs site and product UI). When the post comes in, only assign it to yourself if you're going to see it through from start to finish. Otherwise, you can just monitor it as it goes through the workflow.
Before you start your writing review, make sure it was reviewed by a product marketing manager if the post was from outside that department. For example, if a developer or product manager submits a post, it should be reviewed first by a product marketing manager (anyone listed in the CODEOWNERS file). After a product marketing manager reviews the post and passes it to the hero, make sure you complete the steps in the sections below.
Manage GitHub board
- In the GitHub projects board, move the post from the triage column to the Scheduled work column. The post will remain there until the post is actually published.
- Insert the publishing date and time window into the PR title so it’s easy to recognize. Our instructions tell contributors that we offer these publishing windows: morning, mid-day, or evening. You may need to ask if they want this posted early to ensure it is available on time.
Review the post
Review the doc using our main style guide rules. If you see major issues, work with the contributor (or the product marketing reviewer); otherwise, you can just make the changes yourself.
Confirm that the URLs to the docs site are absolute. Relative paths don't resolve in the product UI, which is why you need to use absolute paths in the posts.
* Absolute path (GOOD): [**Billing user role**](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles)* Relative path (BAD): [**Billing user role**](/docs/accounts/accounts-billing/new-relic-one-user-management/user-management-concepts/#roles)If the post refers to any images, make sure they are not links to images hosted on other sites. Images files must reside in our repository.
Check if the post has the
isFeatured: truein the front matter. If so, this means that the post will be pinned to the top of the product UI. You should remove the corresponding flag in the previously featured post so only one post is featured.
Publish the post
- After you publish the post, perform a second merge to main to push the post into the product UI.
- Follow up and confirm that the post is displayed in the UI, as well as the docs site.
Plan for future posts
For posts that are to be published in the future:
- Generally, the hero on duty takes responsibility for the post on the day it needs to be published.
- If a post needs to go out earlier than the typical 8 or 9 a.m. (US pacific) merge, the hero who worked on this initially should arrange to have this posted.
- In some cases, such as for specific high-visibility releases, a technical writer may take ownership of the posting by assigning themselves to the PR so everyone can see that the hero isn’t responsible for that post.