Release Cycles for Technical Documentation

It’s common for documentation to be tied into product or engineering release cycles, but for smaller companies who want to move faster we advise keeping them separate.

Generally, it’s much better to work ‘in public’ on documentation. Compared to code, it’s much less likely that a bug or issue in your documentation is going to have a big negative impact on your customers. But any improvement has the potential to save many hours of frustration. This means that you often want your documentation to be release far more frequently than changes to your product.

Keeping a separate release cycle also allows your documentation and engineering teams to work faster, with less of a need to collaborate on every change.

Of course the downside of this is that you risk your documentation and product getting out of sync. For mission-critical platforms, this might not be an acceptible risk, but for many products it’s worth the extra speed.

If your docs are out of date for a bit after a product release (or ahead and are already mentioning unreleased features) then this might be annoying to your customers, but in reality most people won’t even notice.

Edit and iterate after publication

For code, you usually want to do code review before pushing changes lives. For documentation, you can often push drafts live and then iterate on them.

There’s a bit of a balance to find (you don’t want to publish anything that’s so rough that it embarrasses you), but in general we think that most companies can err a lot more on the side of publishing unpolished work.

Being able to make changes and get them live with as little friction as possible not only gets useful information in front of your customers more quickly, but it also

• Encourages members of your team to contribute to documentation (it’s very demotivating to spend effort working on improving something only to see it die in some weeks-long review cycle)
• Lets your customers make contributions too. If your documentation is open source and it’s easy to make changes to it, you’ll likely have people who have run into an issue and figured out how to resolve it submit a PR.