The story of Bonita Documentation! From Drupal to GitHub

Have you ever had a question, an issue, a need to know something about Bonita? If yes, you’ve probably visited the friendly Bonita Documentation!

Last March 2021, we launched the new Bonita Documentation site, which provides a lot of fixes and improvements. If you want more details about the new site content, here’s the site go live announcement.

We want to share with you the story of the Bonita documentation evolution. We’ll start with this article, first in a series to explain how and why the Bonitasoft team decided to make this latest change.

Here we’ll describe the previous iteration of the Bonita documentation (may it rest in peace), the fascinating history of our documentation and some of the issues we faced over the time.

In the following articles, we’ll explain the solution we were looking for, the technical choices we made, and what we learned from our new technical stack during the migration.

Bonita documentation: Know the past, understand the present

The Bonita online documentation was revamped in 2016. The previous Drupal-based site was deprecated and a new site, fully custom made, was introduced to host the documentation starting with Bonita BPM v7.3.

This first revision was motivated by the existence of a lot of issues in the existing solution, including:

• Content could only be updated by the Bonitasoft internal technical writer (a single person), so if you saw a simple typo, for instance, you had no way to fix it yourself. You had to reach the person responsible, or create a ticket. This was a bottleneck and led to a lack of ownership in particular by the Bonitasoft Product and R&D teams who never felt motivated to improve documentation because the process was too heavy.
• Versioning was hard to manage, in particular reporting updates from version to version was difficult (and not possible to do automatically), which meant is was often forgotten and not in sync with the Bonita version release.
• There was no real preview of the final rendering prior to publishing to production, which led to mistakes, rework and dissatisfaction.
• Technical updates in the production environment were rare and painful. This Drupal site had been customized by the Bonitasoft IT Team, so Drupal updates needed custom code/configuration as well.
• It was necessary for Bonita users to login to access the documentation, and we may have lost some potential Bonita users because of that. We definitely had users that did not Read The Friendly Documentation!

The development of a new documentation solution started in January 2016 to be ready for the Bonita BPM v7.3 release.

New and improved!

The internal Bonitasoft team decided that the documentation content should be public and hosted in a GitHub repository.

We introduced with the GitHub documentation:

• collaborative contribution flow with Pull Requests only
• content is written using Markdown syntax instead of filling a form using pseudo-wysiwyg text. This separation between the content and its presentation allowed more flexibility (initially we could generate documentation in both PDF and HTML)
• updated content is continuously deployed to production
• a new and better search engine is integrated within the site
• no more login is needed to access to the documentation
• preview environments are available and built in the same way as the production

Photo by Jeremy Bezanger on Unsplash

These improvements fixed the main issues of the previous Drupal solution.

For Bonita users (community or customers), Bonita Documentation site v2016 meant that:

• The documentation content was updated frequently, with a version-to-version report with a Git merge. Small changes could be done by anyone and pushed to production quickly by merging pull requests (and just a few minutes’ wait for the production site to be updated).
• The documentation was released at the same time as the Bonita beta and GA versions.
• Bonita users can contribute directly to the content instead of requesting changes (in particular for very small changes like typos).

For Bonita developers, Bonitasoft Product and Support Teams:

• They can easily produce and update Bonita documentation.
• Documentation issues and feedback can be quickly integrated.
• Contributions are reviewed and discussed by technical pairs to be sure content is accurate.
• Updates are tracked in the Git history for easier content maintenance.

The go live for Bonita documentation on GitHub was announced with a blog post on September 14, 2016, and this solution was used until March 2021.*

Photo by Drew Beamer on Unsplash

Coming soon

Then...everything changed once again. In my next blog post, I’ll tell you why.

Thank you to Laurent Leseigneur and Emmanuel Duchastenier for their review of this article.

*If you want to know more about this first migration, an overall presentation in French is available in a set of public slides (use the down arrow to pass to the next slide). It gives more details about this story, and the technical solution.