This article is about Part 1 of the journey of the Bonita documentation from Drupal to GitHub.
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
These improvements fixed the main issues of the previous Drupal solution.
For Bonita users (community or customers), Bonita Documentation site v 2016 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 peers 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 Bonitasoft Community blog post on September 14, 2016, and this solution was used until March 2021.*
Coming soon
Then...everything changed once again. In my next blog post, I tell you why.
*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.
