3 ms·
Doing docs-as-code by putting documentation in the codebase is somewhat of an oversimplification. Usually, you want to use feature flags to decouple changes in
by solatic 2y ago
Doing docs-as-code by putting documentation in the codebase is somewhat of an oversimplification.
Usually, you want to use feature flags to decouple changes in Product from Engineering-driven deployments, so that new feature work can be rolled out slowly and its impact on KPIs measured, and so that engineering can de-risk the delivery of large changes by putting those changes behind feature flags with 0% rollout.
The problem is, documentation is much closer to Product than Engineering, meaning, doing docs-as-code correctly means putting your documentation behind the same feature flags. So you should have both a public static site that shows the documentation for features whose flags have 100% rollout, plus your application itself should also show the documentation, so that you can show the documentation to users for feature flags enabled for those users.
There aren't really any frameworks that have this docs-coupled-to-feature-flags pattern available off-the-shelf and most companies don't consider it high-enough priority to build in-house.
- ElevenLathe 2y agoThis is an interesting idea. Have you experienced any in-house versions of such a product? Anything that stuck out as good/annoying?
- solatic 2y agoNo, the closest is staging documentation changes until the features reach 100% rollout, then manually pressing a button to try to launch the docs at the same time. But when users don't find docs for new features (that are rolled out only to them), they naturally revert back to trying to talk directly to Engineering, which doesn't scale. An example of this mismatch is when QA isn't testing documentation changes: best-practice QA discovery-testing is for QA to have a production tenant, where the feature flag is enabled only for the QA tenant, but if QA doesn't have documentation for how the feature is supposed to work, then they end up having completely separate infrastructure that nobody else pays attention to, or else QA is talking directly to Product/Engineering, which somewhat defeats the purpose since that's something that customers can't do.