Aiven creates its developer documentation as an open source project, so you too can help! Read on to find out how we use docs-as-code to make this happen.
Floor Drees
|RSS FeedStaff Developer Advocate
Subscribe for the latest news and insights on open source, Aiven offerings, and more.
At Aiven, documentation is a cross-departmental effort. As colleagues, more experienced documentation contributors run sessions to onboard new people and to lend a hand as they make their first edits to developer.aiven.io.
Today we're at a point where we can welcome external contributions. If you’re using our docs and find that something is missing, or you see an opportunity to improve it, then please consider contributing to our growing body of developer documentation.
According to Write The Docs "Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code". That means using issue trackers, version control, plain text markup such as Markdown or reStructuredText, implementing code reviews, and having automated tests for your documentation.
Docs as Code also means following the same workflows as software development teams do, and having close ties with the product team. It enables a culture where writers and developers both feel ownership of documentation, and work together to make it as good as possible.
Developer.aiven.io is open source, just like most of the other things at Aiven. The platform uses open source tools, and the content itself is Creative Commons licensed. We use established workflows and review processes, alongside GitHub for collaboration (and full audit history of all changes). GitHub actions take care of running the automated testing and deployments, including deploying previews for each in-progress pull request.
The tech stack consists of Sphinx plus some excellent extensions, Vale for linting the prose, and MermaidJS for diagrams. We package all this up into a static site to make sure that your docs always load very, very fast.
Here is a little tour of the project to help you get your bearings:
docs/ folder has all the articles in it
CONTRIBUTING file has article templates and a style guide
READMEREVIEWING file covers guidelines for reviewersBefore you start work on something new, check the issue list and assign the issue to yourself or comment on it if there's already an issue there.
Chances are that you already have a developer environment on your machine. Use your terminal or command prompt to clone the repository, create a new branch, make your changes, and open a pull request.
Follow the instructions in the README file to install the necessary dependencies, and make sure to build and test your changes locally.
Using Visual Studio Code? My colleague Lorna Mitchell shared her VSCode setup on her blog.
If you're looking for a GUI (Graphical User Interface) tool, GitHub Desktop is a great option. It's entirely open source too - so you know that we like it!
Download GitHub Desktop if you haven't already, and log in with your GitHub account. Then clone the repository, or if you already cloned it, select File > Add local repository and specify the local path. Create a new branch, make your changes using the editor of your choosing, and commit.
I’m excited that we have enabled Codespaces for this project - hopefully the first of many under the Aiven organization on GitHub. To use Codespaces, select the green "<> Code" button on the repository.
You can either create a codespace on the main branch, or collaborate on a feature branch or PR.
So I might pick a pull request from a colleague, check out the changes they made, and build the site.
And it’s fast too!
We are proud of our documentation project, but that doesn't mean that we're not actively working on it (it's public, you can see that we are!), or that it can't be improved. If you spot something that you think could be better, go ahead and let us know by opening an issue. Even better, make that improvement yourself. One of us will work with you to review the change and then you'll be published in no time at all, earning both gratitude and bragging rights.
Here's a quick run-down of some useful links:
--
If you have any feedback or questions, say hi to us on Twitter or LinkedIn. Make sure you follow our changelog and blog RSS feeds, and if you want the latest news about Aiven and our services - plus a bit extra on all things open source - subscribe to our monthly newsletter!
