Contributing to Aiven's developer documentation

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:

• The docs/ folder has all the articles in it
  • subfolders match the URL structure
• The CONTRIBUTING file has article templates and a style guide
  • some reStructuredText tips can also be found in the README
• The REVIEWING file covers guidelines for reviewers

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!

Get involved

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:

• our documentation: https://docs.aiven.io
• the GitHub project: https://github.com/aiven/devportal
• a handy guide to automating your pull requests using GitHub Actions
• and just in case you're wondering what this Aiven thing is anyway, or you want to try things out so you can document them, sign up for our free trial

--

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!