Contributing to documentation: Aiven Developer
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.
About Docs as Code
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.
Our chosen technologies
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.
Contributing to the project
Here is a little tour of the project to help you get your bearings:
Before 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.
Using your favorite IDE
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.
Using GitHub Desktop
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.
Using GitHub Codespaces
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 reminder of the links you need: