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
The daily hero has the following responsibilities each day:
- Merge scheduled posts: Check the
Scheduled workcolumn on the Github board for anyWhat's newposts that have already been approved and are scheduled to merge that day. For example, if Monday's hero reviewed and approved a post scheduled to go live on your Wednesday hero shift, you should merge that PR. - Review any incoming posts: Any
What's newposts that come in should be reviewed and approved during your hero shift. This includes basic copy edits, ensuring correct image formatting, and confirming a successful preview build. Edit the title to the day it should be published and then move the PR to theScheduled workcolumn. By reviewing PRs as they arrive, you ensure a smooth release once they are ready to merge.
See the rest of the doc for more detailed instructions.
Dica
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.
Dica
If you can't complete a "What's new" post review during your hero shift, please alert the hero taking the next shift so that they can complete it.
Publish the post
Cuidado
Before you create and merge the second branch to main, make sure the GitHub action that generates the ID completes.
There are two merges to main involved in publishing a "What's new?" post.
- Create your daily release branch and merge it to
mainas you would normally. - After merging to
main, go ahead and create a second release branch based offdevelop. This second branch will contain the 'Whats new?' ID. - Merge this second branch to
main. This second merge displays the 'What's new?' post in the UI. (For those curious: the second branch contains a 'Whats new?' ID that connects the post from our docs site to the UI. The second merge accounts for the second location.) - 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.