Early in 2022, we migrated our documentation for iOS at RevenueCat from Jazzy to DocC, and we wanted to share the reasons behind the switch and the process we went through to make it happen.
Why move to DocC?
At RevenueCat, we were interested in DocC since it was announced at WWDC ‘21. It seemed like a promising format, with a clean look that’s familiar to any iOS developer, and lots of potential for documentation that truly guides the reader.
Our docs were previously generated using Jazzy, a great open-source library. While we never had issues with Jazzy, Apple’s DocC promised noticeable advantages when compared to Jazzy.
Here are a few of the reasons why we decided to make the move to DocC.
Format and navigation
DocC allows you to organize the information for the reader, allowing for a nicer introduction into what the SDK does. Most doc generators simply show you a main page and access to all symbols, so new readers don’t know where the entry points to the SDK are and how the symbols relate to each other.
This however can easily be done with DocC: you can generate Topics and better organize the docs. This way, the symbols can be cleanly organized into logical sections, like “Configure the SDK” and “Displaying Products”, instead of a disorganized list of all the things the SDK can do.
The resulting documentation is more readable and the overall design is more polished. It even supports Dark Mode!
But you don’t have to take my word for it. Check out the last version of docs we generated using Jazzy and our current version using DocC.
Checking for linked symbols
This was ultimately what made us make the jump to DocC: we wanted to have a clear way to know if we have a symbol linked in our docs that’s out of date.
There is a Build Setting in Xcode (RUN_DOCUMENTATION_COMPILER) that allows DocC’s compiler to generate warnings if a symbol in the documentation doesn’t match the source code, which helps ensure that our documentation stays up-to-date and accurate. This is covered more in detail later in this post.
IDE integration
Figure 1. DocC integrates seamlessly with Xcode.
Another big benefit of DocC is that it is backed by Apple, which means it is well-supported and integrates seamlessly with Xcode. The docs generated through DocC look the same as the ones you get when you select “Show Quick Help” (or ⌃⌥+click on a symbol) in Xcode, which makes it a lot easier for us to ensure that the Quick Help section looks correct and is easy to read.
Future improvements
Interactive Tutorials look really promising, although admittedly we haven’t created our first one of those yet. We’re looking forward to trying them out!
Apple has been hard at work improving DocC and adding features to it, including a Swift Package Manager plugin and the ability to easily host DocC docs in GitHub Pages.
How we migrated without stopping development
1. Update our docs to common format between Jazzy and DocC
Our first priority when deciding to try out DocC was to retain the ability to make releases and generate documentation while we’re still migrating docs.
The first step towards this goal was to update our documentation so that its formatting was compatible with both Jazzy and DocC’s formats. This was important because it allowed us to easily switch between the two while we were testing and making adjustments.
Luckily for us, Jazzy adopted most of the format conventions that DocC uses, so updating our docstrings to DocC format was easy to do.
Figure 2. Jazzy adopted most of the format conventions of DocC, making updating easy.
2. Enable DocC documentation compiler to fix typos in symbols
Some of our old docs had typos in the links to symbols in the SDK. We set the build setting in Xcode called RUN_DOCUMENTATION_COMPILER to Yes, which compiles docs when you build the project. This step is thankfully very fast (~0.2 seconds for our SDK), and it adds a build warning if a symbol isn’t correctly referenced. We used this to clean up our docs.
Figure 3. When compiling documentation in DocC, warnings are given when symbols aren’t reference correctly.
3. Take advantage of DocC’s power
Once we had basically the same docs generated with DocC instead of Jazzy, we could truly start to work towards making them more useful. One of DocC’s best features is the ability to organize the docs into Categories and Topics, allowing for a clearer structure.
This allows us to design the flow of information that a reader first sees when going into our docs, to make it as easy to navigate as possible.
Figure 4. DocC allows you to organize docs into Categories and Topics.
4. Hosting in GitHub Pages
We moved the documentation into GitHub Pages and set up a CI job to automatically generate and deploy the docs with each release of a new SDK version.
When we started working on this it was a lot harder to do because you needed to export an archive of the docs from Xcode and then do some work on top of them to publish them. But, thankfully, Apple added support for exporting for static site hosting.
Apple has a tutorial for how to host docs in GitHub Pages, so we won’t duplicate it here, but the basic command is:
Figure 5. The command for publishing docs to GitHub Pages.
We also added a fastlane lane to preview the docs locally so we could check for formatting errors before publishing a new version.
5. Versioning
While we love DocC and at this stage we have a pretty clear picture of how to publish docs, there’s one problem that DocC has no answer for: having different versions of docs for different versions of an SDK.
Ideally, we would want a version selector that you can use to navigate to the version you want and you’d be directed to the latest version by default.
However, there’s no way to achieve that using just DocC.
Instead, what we did was:
- Create a new folder which has a subfolder per version of the SDK.
- Host all the docs in a new repo, so that versions are independent of branches in the source repo. This allows for us to develop on one branch while the docs repo gets updated for latest releases separately.
- Create a new page that redirects the user to the latest version of docs if they navigate to the root of GitHub Pages.
- Add a step that updates that redirect page in CI when there’s a new release to make it point to the corresponding new version of the docs.
You can see how this is structured in our docs repo here. The corresponding CI job is located here in our source repo.
Conclusion and future
DocC has been a big improvement for our SDK Reference Docs at RevenueCat. While we’re happy with the result, there are a few things we’d like to do in the future:
- Introduce interactive tutorials for our main use cases.
- Add a version selector (please, Apple, add support for this!).
- Introduce a language selector to be able to see the Objective-C docs (hopefully coming soon!).
The actual migration path was thankfully not difficult, because Jazzy is compatible with most of DocC’s format. And we can now rest assured that the symbols referenced by our SDK are correct.
Take a look at our SDK Reference docs and let us know what you think!
Top comments (0)