We’re incredibly excited to announce that Doctave’s developer documentation is publicly available. You can find it at https://docs.doctave.com.
Our closed beta in Doctave since October 2022. So far all our documentation has been behind a password, meaning that only teams part of the beta were able to access it.
We thought we would talk a bit about how our documentation evolved with a fast-moving product, how we handled releases, and how we eventually had to take a step back to rewrite most of the documentation.
The birth of our docs
We have been self-hosting and dog-fooding our own platform with our docs since the first day it was possible. Back then, Doctave was a much simpler product and could not do much more than display your Markdown pages.
In fact, here is a screenshot from July 2022, of the very first production upload ever done on Doctave:
(Since we are using Doctave ourselves, we can time travel to any point in time to see what our docs looked like.)
Since then, the platform has come a long way. Over time we have added:
- OpenAPI support
- A flexible versioning scheme
- Dynamic content with user preferences
- Feedback collection
- And many many other features…
What we ended up doing, somewhat naively, was keep adding sections to the left navigation. When a new feature was added, just add another page.
(This screenshot is from a build from December 2022.)
The problems we faced
At this point, our docs were not great. There was no consistent naming for concepts, some content did not have a natural home and was duplicated, and it was generally hard to find out how achieve certain goals using our docs.
In other words, our information architecture was bad.
In fact, what happened was very analogous to technical debt. We had kept adding content (or “features”) to our docs without stepping back and thinking if this was the best place for it. We had not refactored our documentation as it grew.
We were saved only by the fact that we had set up shared Slack channels with our beta customers, so we could quickly respond to queries.
What is good documentation?
So this year we took a step back to rewrite our documentation. We decided to practice what we preach and think carefully about what the structure of our documentation should look like.
Our documentation should consist of 4 general sections:
- A getting started guide
- Higher level articles about Doctave works
- How-to guides for specific tasks users want to do
- A reference for documenting the details of our APIs
I invite you to look at our live documentation and see if you can guess which page maps to which category.
(Our live docs at the time of writing.)
At the top we have an extensive “Getting Started” section that walks users through creating an account, their first project, and publishing documentation.
We have some higher level explanations about topics like docs-as-code that give the reader an overview of how Doctave works.
Instead of writing about features, we named our articles from the perspective of tasks the user is trying to compete.
Finally, we have an extensive reference for our configuration files, supported Markdown features, and Liquid Template Language.
Documentation requires attention
I’m reminded of a story of a cobbler and their children for some reason…
Documentation requires a lot of explicit thought and attention. Just like code, it can easily rot and become harder to understand if you do not take the time to “refactor” and clean up your content.
Today we are in a much better place. All content has a clear home. In fact, as we were writing new articles, we rarely wondered “I wonder where this should be placed?”. Everything seemed to have an obvious home.
The work continues! Our docs are never done, so we will keep updating as we release new features and improve our guides.
We invite you to give us feedback on our documentation! You can find a feedback button at the bottom of each page. We read every comment!
Now, go and have a look yourself: https://docs.doctave.com/.
Articles about documentation, technical writing, and Doctave into your inbox every month.