CONTENT ARCHITECTURE | SINGLE SOURCING
Okta publishes weekly release notes that include details of new features and bug fixes available to organizations. An Okta org has two versions: Classic Engine and Identity Engine. Additionally, there are two types of environments: Preview and Production.
This combination means there are four types of orgs and each has separate release notes:
- Classic Engine Preview
- Classic Engine Production
- Identity Engine Preview
- Identity Engine Production
Challenge
Release notes include the following sections:
- Generally available features
- Early access features
- Bug fixes
- Okta Integration Network (OIN) updates
Some features and fixes are available to all orgs, thus this content is common across all release notes. Some features are available on select orgs. This content is specific to that release notes.
A release note can contain as many as 25-35 feature updates and the equal amount of bug fixes and OIN updates. Multiplied by four release notes at least three times a month, the content quickly adds up. Given that a significant part of this content is common across all release notes, this was leading to heavy content duplication.
Moreover, certain updates are released to orgs in stages. For example, a feature is released on Preview orgs in a release no. 1 but it’s released on Production orgs in release no. 2. Some features have a predicted path of release, while some don’t. This added to the content duplication.
Solution
To address this issue, I leveraged single-sourcing techniques in MadCap Flare. I used snippets and conditions to create one file set that can be published in four places with customized content.
Release Notes template
The file set is created as a template folder that can be used every month to create new release notes.
- The templates include snippets for each release notes sections.
- These snippets are mapped to Preview and Production snippets. This allows the reuse of the content that’s common across all release notes.
- Two sets of conditions help in publishing only relevant content for specific release notes and hide rest of the content.
- The first condition set is environment-specific. This allows us to publish content depending on whether it’s applicable for Preview or Production orgs.
- The second set of conditions is version-specific. This allows us to publish content that’s applicable to Classic Engine or Identity Engine.
- These conditions are applied to features and fixes depending on where it should be published.
- The snippets also have conditions at the snippet level to hide certain content from release notes.
Once the content is added into the right snippets and the right conditions are applied to it, four versions of release notes are automatically and accurately generated from one set of files. This architecture reduces the amount of time and the number of files required for release notes by 75%.
See the latest release notes:
Production Release Notes – Classic Engine
Preview release notes – Classic Engine
Nikita Apraj 