DEV Community

Cover image for Robots writing docs
Omri Lotan
Omri Lotan

Posted on • Originally published at Medium on


Robots writing docs

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

Alvy publishes our documentation (portrait by janko_m)

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

Alvy pretends he’s creative with his commit messages

Alvy’s handy-work in “Futile” documentation

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.

CircleCI enable/disable automated tasks for forked branches

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.

Top comments (0)

An Animated Guide to Node.js Event Loop

Node.js doesn’t stop from running other operations because of Libuv, a C++ library responsible for the event loop and asynchronously handling tasks such as network requests, DNS resolution, file system operations, data encryption, etc.

What happens under the hood when Node.js works on tasks such as database queries? We will explore it by following this piece of code step by step.