Update method for documenting features with flags
How we document features with flags, currently
We’ve done a lot of good work identifying how users interact with feature flagged features. However, the way we display this information in our product documentation could be improved.
Some issues with our current implementation include:
- Information hidden in the version history.
- No single source of truth for how to enable or disable feature flags. Instead, it's repeated for each feature.
- Duplicate information in the version history and on the page itself.
- The enable/disable information is not physically proximate to the main feature header. (It's close, as a subsection, but there's information between the enable/disable and the feature name itself.)
- A developer focus on how we present the information, instead of a user focus.
Information about feature flags should be in a Note at the start of the topic (just below the version history).
The note has three parts, and will follow this structure. (This is not the exact text. This is a structure you'll fill in with specific text.):
NOTE: <Self-managed GitLab availability information.> <GitLab.com availability information.> <This feature is not ready for production use.>
Here are the options for each of the three parts:
Self-managed GitLab availability information.
|If the feature is...||Use this text|
GitLab.com availability information.
|If the feature is...||Use this text|
If needed, you can add this sentence:
This feature is not ready for production use.
A few notes about this approach
With this structure, we would document how to enable or disable a flag in one central location. The note includes the feature flag name, and the topic we point to tells them how to enable/disable a feature flag.
Based on the tier badge, you can omit the self-managed or GitLab.com sentences. For example, you can omit the GitLab.com sentence for a feature with a
**(FREE SELF)** tier badge, because the feature is not available on GitLab SaaS.
As an example, let’s use https://docs.gitlab.com/ee/user/profile/account/two_factor_authentication.html#one-time-password-via-fortitoken-cloud and see how the proposed feature flags would work:
> Introduced in GitLab 13.7. NOTE: On self-managed GitLab, this feature is not available due to the `forti_token_cloud` flag, but [you can enable it per user](<path to>/administration/feature_flags.md). The feature is not ready for production use.
If it were to be updated in the future to enable its use in production, you can update the version history:
> - Introduced in GitLab 13.7. > - Enabled for self-managed GitLab in GitLab X.X and ready for production use. NOTE: On self-managed GitLab, this feature is available, but can be hidden per user by [updating the `forti_token_cloud` flag](<path to>/administration/feature_flags.md).
And, when the feature is done and fully available to all users, you’d have:
> - Introduced in GitLab 13.7. > - Enabled for self-managed GitLab in GitLab X.X and ready for production use. > - Feature flag removed in GitLab X.X.
We’d like for the team’s input regarding this proposal, and if there are any issues with it. Is anything missing? Are there any opportunities for people to get confused? Are there things our current implementation covers that this does not?
The deliverable for this issue is a workable solution that ends up with a linked MR to update the Style Guide with information about this standard and its use.
Afterward (and outside of this issue), we’d then need to separately:
- Update the https://docs.gitlab.com/ee/administration/feature_flags.html page to work more effectively with the new structure.
- Create backlog issues to over time update our documentation that refers to features that have flags to use the new structure.