Product release: Versioning & Bulk Publishing
• Dec 13, 2023
We’re very excited about this release, partly because it came together in a great team effort (it touched 40% of our code), but mostly because these features are commonly requested by our fans and users.
Outdated documentation is a major problem, hence, keeping documentation in sync with code and API changes is vital to reduce support requests and speed up integrations. You don’t want to release documentation before the code is there, nor do you want to release code without documentation being available. By combining bulk publishing (several changes at once) with version control you can now work on larger releases or content changes easily.
Version control might be a contractual obligation you have to comply with - or a value-add you want to offer to your customers. Either way, you can now easily implement versions and you’ll have granular control on the visibility of any version you create.
Read along to find out more about the specifics of this release, or dive into the below video that explains how to version & publish docs inside Alphadoc in 3 minutes.
Versioning & bulk publishing
How to use it
All published content has the default version v1.0. Any content that is not yet released has been added to draft and can be seen directly in the editor. Within the editor you can either start from scratch with a new version, or duplicate the existing docs and APIs. When you are ready you can hit Publish to push everything in one go!
When to use it
When creating a new version to retain internal copies, but publicly showing one version
You are introducing a new version with many breaking changes in your API - warranting a thorough rewrite and restructure of your content
You are adding a big new feature with multiple documents and APIs - you can now easily keep your work in draft until you are ready with all the content at once and publish it
Common questions and answers
Will links and URLs continue to work? Yes, they will automatically update whenever you publish a new version
Is any content excluded from versioning? Yes, only the custom styling (typography, colors) is excluded from versioning and will be applied immediately across the docs
What do the labels in the versions overview mean? A version can be set to ‘latest’ which means it is visible on the homepage and ensures that you can link to the homepage without having to add a version number in the URL. The ‘current’ label indicates the version that you are editing.
I don’t want to make use of versions, is that possible? Yes, default your documentation has v1.0 and you can keep making changes and publishing them on the same version, and the URLs will not be impacted.
New header design
We made changes to the header design to improve accessibility to key features. We also nested API references in one selector to prevent them from cluttering your navbar.
To start building your docs & DX with Alphadoc, sign up here. After sign up, you can upload your OpenAPI spec and easily create a compelling developer experience, that stays up-to-date.