Thesis: Automated build of Onebip’s documentation

By Giorgio Sironi, Onebip Tech Team

We are proud to announce the first Computer Science thesis started and completed inside the Onebip team. Daniele (from the Onebip Tech team) has finished his internship and is graduating at the end of February (2014) with a Bachelor in Computer Science at the Università degli studi in Milan, Italy. We’d like to thank professor Carlo Bellettini of Italian Agile Day’s fame for letting Daniele work with us.

Daniele's thesis in Onebip title page

His work of several months in Onebip has been to automate the generation of documentation, mainly of the mechanism we use to update technical PDF documents for merchants that need to integrate us. The documents’ contents run from sample API calls and code to textual descriptions and tables describing the possible notifications made by our systems.

We started from Word .doc files that need to be checked out of a repository by one person at a time, with an exclusive lock. Once the developer has finished updating the relevant paragraph and fighting Word, he had to export manually a PDF version of it and check in on the repository.

After re-engineering this process, a developer can now update the documentation without exiting his development environment (from Vim or his preferred IDE). Documentation is written in GitHub Flavored Markdown, little more than plain text and HTML, and is versioned ,in a repository identical to the ones used by all other Onebip projects.

We now have the tools that:

1. Check out automatically the latest version of documentation source code from its repository.
2. Build it transforming Markdown in a PDF file virtually identical to what was manually exported before.
3. Upon manual approval, publish the result on a public URL that can be linked to from Onebip’s corporate website.

The friction for developers is reduced to a minimum, as they work on the documentation in the same way as the source code; we’re targeting an update cycle time of an hour that comprehends checking out, editing, checking in and publishing. This will ensure merchant can get an up-to-date documentation.

No more fighting with Microsoft Word for developers (not even opening it). No more manually syntax highlighting of the code samples, or copying and pasting them from external tools. No more versioning in names as in filename_1.3.4.

Are you a Computer Science or Computer Engineering student near Milan and want to work on a thesis in an Agile environment? Want to learn something you can’t find inside the university? Want to build something cool and useful instead of slaving away on your professors’ research projects? Contact us!