Robots writing docs

Sep 16, 2017 · 3 min read

Automating code documentation tasks @ Fiverr

Following a commenting guideline

The popularisation of documentation automation tools like javadoc and jsdoc has re-introduced the standard of commenting guidelines. Keeping a uniform comment style is beneficial for the same reasons code style guides are; it contributes to conformity of code, ease of peer reviews and collaboration and minimises research efforts for unfamiliar parts of the code-base.

Readable code, Well commented code, Documentation.

When we select libraries to use in our own program, we require an accessible documentation. We check for one before (if at all) reviewing their code base. We consider it a necessity of external solutions. As our company grows, we begin to understand this feature is as important for internal projects and packages. Our developers will start using the tools we build without diving into the details. Top level documentation can accelerate implementation.

Starting to document your code according to a guideline seems tedious on it’s own, practices of readable code suggest it is redundant. I’m doubtful most developers will sustain such a paradigm, but if it was accompanied by instant gratification, the benefits are more visible.

Inline documentation

This is where inline documentation and automation tools come in.

Since comments accompany definitions in the source code, structured comments become part of the peer review process and their formatting becomes part of our organisation’s code styling guide. Peers start to demand readable, well formatted documentation to perform their code review.

Keeping documentation concise and readable becomes a necessity. Otherwise, it will take over entire files. The rule becomes: “If you can’t explain your method in a sentence, chances are you need to break it down.”

Variables and constants are also being documented. This means we are able to use a bit less descriptive variable names when they get too long.

The fulfillment: accessible documents

At Fiverr, we’ve started composing automated tasks for creating documentation out of structured comments.

On one of our open source repositories, for example, the CI (continuous integration) pipeline job carries the credentials for a dedicated user, Alvy. This user was assigned writing privileges on certain unprotected branches of the repository.

Alvy’s work begins when code is being pushed to the main branch. It will build and update the documentation, pull “gh-pages” branch and publish changes, and eventually trigger an update in the dedicated web page.

This is a shell script running on the CI pipeline

The script builds documentation on gh-pages branch each time we update the master
Alvy pretends he’s creative with his commit messages

Eventually, a lovely documentation website is created, automagically, each time the main branch updates.

A word on security

For open source projects, it is important to notice what can happen in pull request branches where the CI carries privileged credentials.

One option most CI providers offer — is to turn off the build for forked pull requests. We find this solution may create difficulty for contributors.

Our answer to this issue was to grant our documentation user, Alvy, limited privileges, making sure it is not able to alter any of the production branches by applying protected branches policy.

Alvy is also not a member of our developers group, so it can’t clone, pull or fork any of our private repositories.

Fiverr Engineering

The technology behind the platform that’s disrupting the…

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store