Robots writing docs

Automating code documentation tasks @ Fiverr

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.

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.

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.

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

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

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

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.

Related posts:

We have all been students once, as we remember the struggles in getting quick cash while endless searching for professional jobs. Students register to bitJob marketplace and can choose to deliver…

Black fox was my main area of design this trimester and by far the most agonizing. I made several things for Black Fox which were; logo, poster, black and white cardboard packaging box, stickers…

Working capital finance, properly structured, can provide the boost your business needs to both grow and operate. Businesses take on the lack of cash flow challenge for a variety of reasons: The…