claromes.com

In July of this year, I was accepted into the GitLab Heroes program after making small contributions to the GitLab documentation. Last month, I made my first contribution as a Hero: I wrote the documentation for the GitLab Advisory Database (internally referred to as GLAD).

I divided the process into two parts: Research and technical writing.

I already have an interest in the field of information security, so I'm familiar with the terminology, best practices, and, being a developer, I understand the importance of keeping project dependencies up to date. Therefore, documenting a database that provides maintainers with information about vulnerabilities seemed interesting to me.

One of my references was this blog post on GitLab, which I recommend reading if you want to use the database for free. Another reference was this excellent playlist on Continuous Vulnerability Scans, which helped me create a graphic using Mermaid to illustrate the use of GLAD.

By the way, Mermaid is a great tool for creating diagrams, especially for those who are familiar with markdown. I write my blog in markdown, but it doesn't render mermaid code. However, you can use it for .md files in GitLab or GitHub.

Before getting interested in documentation, I took a short course from GitLab itself, which helped me understand some rules of technical writing and also the rules used for documenting GitLab. It was helpful, and I recommend it to anyone working with software. Documentation matters!

I'd like to highlight some things I always do in these contributions:

• Write a first version with just the page outline to help with organization.
• Apply the Style Guide by using a checklist.
• Use the Style Guide as a reference (which is up-to-date) rather than using previously written documentation as an example (which may have been done before a Style Guide update).
• Take a look at the automatic Code Quality review in the pull request.
• Use friendly writing.

The GLAD pull request was reviewed very quickly due to the need to document the database. Thanks to Russell Dickenson, Senior Technical Writer, and Isaac Dawson, Principal Vulnerability Research Engineer.

The documentation is available in release 16.4 and can be accessed here.

Photo by © maxpix.com

— Claromes