Publishing Content with Staging
A dedicated environment to preview all content and settings changes. Publish to production when you're ready.
What is Staging?
Staging, available only with ReadMe Enterprise, gives Enterprise Group Admins extra reassurance and control over the content of their live developer hubs. With Staging, project settings and content changes are saved to a Staging environment for review, rather than instantly going live. This gives Enterprise Group Admins a safe sandbox to preview changes across all their projects before they’re promoted to their live developer hubs.
Here’s a live walk-through to see Staging in action!
Benefits of Staging
With Staging, Enterprise Group Admins have peace of mind knowing that nothing is published to their live developer hubs until they’ve promoted (and confirmed!) changes from Staging to Production.
Additionally, Staging offers:
- Greater control and flexibility 💪 : Enterprise Group Admins have more control over when Staging changes are promoted and can choose whether to Promote changes only related to a single project, at the Enterprise Group level, or to Promote All changes currently in Staging.
- Less internal coordination ⛓ : per-project promotions allow individual teams to work at their own pace. Each project team within an Enterprise group can save changes to Staging when they’re ready, and the Group Admin can immediately review and promote them—without any dependency on other teams’ workflows or schedules.
- Better visibility and previewing 🔮 : Enterprise Group Admins can filter Pending Promotion changes by project or by promoter, and can also view previously promoted changes in Promotion History. Additionally, Project Admins and Viewers can preview Staging in the hubs of child projects they’ve been invited to.
Enablement
Interested in enabling Staging for your Enterprise Group and/or learning more about the benefits of Staging? Reach out to your Enterprise PXM!
Staging Looking a Little Different to You?
In April 2022, we removed ReadMe code deploys and fixes from Enterprise Groups’ Staging flows, reducing clutter and allowing Enterprise Group Admins to have greater control over their Staging production schedule.
As of September 2022, we rolled out a major update to Staging, and it’s the first launch in a series of Editing and Publishing Workflow upgrades to come! 🎉
Navigating Your Staging Page
Staging lives as the top page of your Enterprise Group dashboard. All Enterprise Group Owners and Admins can view the Staging page and promote changes to production.
Here are the key controls in your Staging page:
- Click Preview to be taken to the main page of your Enterprise Group’s live developer hub. You will be taken to the Staging environment
- Click Promote All to promote all changes across child project, Enterprise Group settings, etc. to Production
- If there are no changes currently saved to Staging, the Promote All button will be disabled
- Use the Filter by Project and Filter by Promoter features to more easily locate a specific change
Pending Promotion Section
All projects across your Enterprise Group with staged changes will be visible in the Pending Promotion section, where they are grouped by project. Any changes that have been made at the Enterprise Group level are held in a separate project and have a “Group” sticker to indicate that they are group-level changes.
The following types of changes will appear in the Pending Promotion section of your Staging page:
- Edits to pages, creating new pages, deleting pages. Includes published and unpublished pages
- Creating, editing, or deleting sections in any of your child projects, e.g. Landing Page, Changelog, Custom Pages, etc.
- Editing or enabling project settings in any of your child projects or at the Enterprise Group level
- Merged or rejected Suggested Edits
Clicking the SHOW CHANGES button next to each project reveals all changes for each project, grouped by individual page changes. Each listed change includes details about:
- What type of change occurred (e.g. Edited page “Name of Page”)
- When the change was made and saved to Staging
- Where the change appeared (e.g. Configuration, Changelog, etc)
- The initials of the team member who saved the change to Staging
| Element | Description |
|---|---|
| SHOW CHANGES | Reveals all staged changes for each project |
| HIDE CHANGES | Minimizes individual project-level changes and only shows the name of the project with staged changes to be reviewed/promoted |
| Number next to SHOW / HIDE CHANGES | Corresponds to the number of per-project changes that are pending promotion |
| Dropdown arrow next to SHOW / HIDE CHANGES | Clicking the dropdown arrow reveals a menu of options: (1) promote changes to Production for just this project, (2) navigate to this project’s dashboard, and (3) preview this project’s live hub |
| Preview link | Enterprise Group Owners and Admins can click the link, where possible, in the listed change to preview it in context. The link directs to the page in the Project or Enterprise Group dashboard where the change can be reviewed and/or further edited (and re-saved to Staging) Preview links are only available for changes made to the API Reference, Guides, Changelog, and Appearance- or Configuration-related changes |
| Left-most icons | Corresponds to where the change was made (e.g. Guides vs. Changelog vs. Appearance) |
| Icon appears in green | Signifies that a change is a net-new creation Green iconography only applies to content changes made across API Reference, Guides, Changelog, Custom Pages, and Recipes |
| Icon appears in yellow | Signifies that the pending change is an edit to something that already exists Yellow iconography only applies to content changes made across API Reference, Guides, Changelog, Custom Pages, and Recipes |
| Icon appears in red | Signifies that a change relates to a deletion of content Red iconography only applies to content changes made across API Reference, Guides, Changelog, Custom Pages, and Recipes |
| Right most phrase (e.g. Configuration) | Corresponds to what page/ReadMe section the change was made in Possible options include: Guides, Reference, Recipes, Changelog, Custom Page, Appearance, and Configuration |
All Projects Section
This section lists all child projects in your Enterprise Group. Each project includes a record of all previously promoted-to-production changes, which is visible by clicking the Show History button. Clicking Show History reveals the five most recent promotions, where specific page-level promotions are stored in each dropdown. Load More reveals more historic promotions. Similar to the Pending Promotion section, Enterprise Group level changes are held in a separate project and identified with a “Group” sticker.
Landing Page Customizations
If you are using Staging to preview landing page customizations, make sure your landing page is enabled. Any landing page customizations are saved to Staging, so they won’t be public to your users until you hit Promote. You can then continue to make changes to the landing page and preview them on the Staging environment!
Global Landing Page Redirects
If you notice that your production and staging preview links go to the same link, this is likely due to a GLP redirect (you can check this under Appearance > Global Landing Page in the parent project).
This can be fixed by changing the redirect to a relative path. For example, if the redirect is
<https://docs.readme.com/docs>, the relative path would be/docs.
To help distinguish between Staging and Production, you'll see this banner at the bottom of the page when previewing your changes in Staging.
Promotion Permissions
| Permission | Enterprise Group Admins | Project Admins and Project Viewers |
|---|---|---|
| View Staging in Enterprise Group dashboard | ✅ | |
| Promote changes from Staging to Production | ✅ | |
| Preview staged changes in a project’s dashboard | ✅ | |
| Preview staged changes in a project’s hub | ✅ | ✅ |
Group Admin Permissions = Group Owner Permissions
Enterprise Group Owners have all of the same Staging permissions as Enterprise Group Admins
If you would like to grant Staging promotion privileges to a Project Admin, you’ll need to change their permission role to Enterprise Group Admin to give them access to the Group dashboard. You can change their permission in the Teammates page of your Enterprise Group.
Previewing Staging in the Hub
As part of the September 2022 upgrade to Staging, we introduced functionality that allows Project Admins and Project Viewers to be able to view Staging in the developer hubs of projects where they’ve been invited as Teammates.
Project Admins and Viewers can view Staging by clicking the dropdown menu in the top navigation bar of a project hub. From there they can toggle between the Production (live) site and the Staging version.
Note: Project Admins and Viewers will not be able to make edits when previewing staged changes from the hub. Enterprise Group Admins can also preview Staging from the hub, but can only make changes from the project’s or Group’s dashboard.
Enterprise group must be public
In order for Viewers to preview Staging in the Hub, the Enterprise group must be published first. This setting is located in the Enterprise dashboard on the Group Settings page.
URL Structure
We use the subdomain of your ReadMe project for your Staging URL. For example, if your custom domain is docs.example.com and your subdomain is example-docs, your URLs will be as follows:
- Production - https://docs.example.com
- Staging - https://example-docs.readme.io
Having a Custom Domain is Key!
You must have Custom Domain enabled in your Enterprise Group dashboard in order to successfully toggle between Staging and Production modes of your developer hubs. Your PXM can help with setting this up!
Updated about 1 year ago