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!
In March 2021, we launched the new Bonita Documentation site, which offers 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 in a series to explain how and why the Bonitasoft team decided to make this latest change.
In our previous article, we described the fascinating history of the Bonita Documentation site 2016 version.
Here we’ll show some of the issues we have faced over time and the solution we have been looking for to resolve them.
Issues with Bonita Documentation 2016
The Bonita Documentation 2016 version was designed to manage documentation for Bonita Studio and Bonita Runtime only. By 2020, it was unable to support new needs, and we faced major issues in the user experience, maintenance, and operations that couldn’t be solved easily.
User eXperience
Improvements made with the 2016 version of the Bonita documentation mainly focused on the content and how to update it, but not so much on the User eXperience (UX).
The site didn’t have a useful bookmark system. There weren’t real anchors in its pages, so it was hard to bookmark a specific section and to navigate between related content on pages and sections.
The embedded search feature was also limited due to the lack of proper anchors. Clicking on a search result didn't send the user to the paragraph that matched the search request, but to the top of the page instead. There was then no other choice but to scroll in the page looking for the expected paragraph.
“Recycling” by Griszka Niewiadomski
SEO was also an issue. Some pages of very old documentation versions were better indexed than their related page in the latest version, so search engines sometimes led the reader to outdated content. Navigation to new content required extra clicks and extra searches in the documentation site.
One of the impacts of these issues was that readers could too easily miss the information they were searching for. This was not the best user experience and we wanted to do better.
Maintenance
The Bonita Documentation 2016 version involved custom Python scripts to aggregate document contents coming from various sources, using one repository per documentation component and a branch per version.
This documentation content structure worked perfectly well, as
- branches were useful for for updates backport/cherry-pick/merge
- repositories were useful for content segregation, access management, product and documentation lifecycle alignments.
Each branch in each repository was responsible for generating its documentation part; the aggregation scripts were in charge of assembling everything and adding the final styles.
Initially this worked well, as there was only a single documentation component (the Bonita platform) and only a few versions.
Over time though, the Bonita portfolio has grown and now contains more products (including Bonita Continuous Delivery, and Bonita Cloud), so more components and more versions were added to the documentation.
Duplications of repositories began to appear and we had to make changes in multiple places. Inevitably more and more problems arose. For example:
- At one time, it was possible to generate a PDF file for a given version of a component. This function was abandoned as it did not work properly, but was still present in all branches.
- The build process of all versions was full of unused tools and dependencies. This slowed down the build.
- We accepted changes in Markdown with custom syntax (for instance, to manage information and warning blocks), native HTML tags, and Font Awesome icons. But minor changes then had to be replicated to all repositories.
As noted, the Bonita Documentation 2016 was complex and hard to maintain. It used an aged technical stack and it was especially hard to build. Developers who may have been able to implement changes were not very encouraged to do so!
We saw very few technical updates, fewer and fewer bug fixes, and the user experience issues remained.
Operations
The Bonita Documentation 2016 version had continuous deployment and preview environments. This was perfect for day-to-day work; changing the documentation content was straightforward. The changes were propagated from staging to production transparently.
“Pull Request Flow” taken from the Agile Grenoble 2017 presentation “Fluidifier la production de la documentation”
But we also faced operational pains.
Adding a new component version (for instance, when preparing a new Bonita beta version) involved multiple actors and synchronization.
- The configuration to actually manage the version was spread across several locations.
- Synchronization was done using tickets, and direct conversations.
This lack of ability to self-service updates slowed down the process a lot and generated frustration.
The documentation site build, and deployment to the preview and production environments, were all managed with internally-operated Continuous Integration servers (Jenkins).
Internally-operated meant dealing with Jenkins and server updates. As it involved a large amount of custom scripts and Jenkins jobs, this also meant maintenance to follow the Jenkins evolutions.
The pre-production and production environments were composed of front-end and search (Solr) servers, also operated internally. This was another area for regular maintenance costs.
As we didn’t rely on a CDN, the latency could be high depending on the location a user was browsing the documentation from.
The previous Drupal-based documentation
Prior to the Bonita Documentation 2016 version, Bonita documentation (for Bonita BPM v6.0 to v7.2) was managed on Drupal.
This content had to stay online for a transition period, up until the versions reached end-of-life. As often happens with legacy assets, it was still available years later.
There were no plans for decommissioning or migrating, and it contained very old content which hadn’t been updated for a while.
It had its own dedicated infrastructure still live more than 4 years after the rollout of the Bonita Documentation site 2016 version. The operations team had to deal with security (stack hard to update) and user experience concerns (no changes to the site while browsers have evolved, resulting in some broken features).
Photo by Thiébaud Faix on Unsplash
The New Solution: What We Dreamt About
All the issues explained above began to have more and more impact on Bonita documentation users. We really wanted to get in there and improve the site!
We first prototyped a new solution based on Jekyll for HTML generation, keeping most of the existing Markdown content and the Python aggregator. We also investigated moving the search solution from Solr to ElasticSearch.
While having a true static site was a great improvement, a lot of issues remained unresolved.
The prototype only addressed a part of the user experience issues; maintenance and the operations sides still presented issues. The site still included a lot of custom code in particular for the content aggregation.
So this approach was not a game changer, although it was a way to do basically the same thing better. But ultimately it didn’t provide enough improvements.
So we decided to change our direction, go back to simplicity, and approach everything globally.
User experience (UX)
The first prototype confirmed that we needed a static site that could provide a good UX especially on mobile (which wasn’t that good in the existing site) and good SEO out of the box.
Maintenance
Reducing maintenance time and complexity was one of our main concerns.
We needed a simpler solution to maintain and deploy; we wanted to rely on existing and widely used tools (a lot of products have the same documentation needs as ours, so solutions exist for our use case), and reduce customization at the minimum (theming).
The Bonita Documentation site 2016 version worked perfectly for porting documentation content changes from version to version. We wanted to keep that, but have a simpler build that wouldn’t be split across repositories.
For a long time, keeping Markdown as a markup language was mandatory. We wanted to avoid doing content migration and training documentation contributors, but this should not stop us from using a better adapted solution if it supports only other languages (as long as we can migrate the existing content and it is easy to learn). We wanted to have a markup language for text diff/merge with Git and Markdown was one way to achieve that.
Operations
We needed to get rid of silos, to have a more self-serve solution to avoid tickets, team synchronization issues, and bottlenecks.
This also meant using configuration as code as much as possible, and automation for continuous preview and deployment. So we imagined a more comprehensive solution where we would no longer operate the Continuous Integration/Deployment, search, and front-end servers ourselves.
We wanted to focus on using them, not on maintaining and upgrading them. So we felt that this would probably involve using a PAAS solution, to provide more features for High Availability and Content Delivery Network.
For the old Drupal solution, we decided we needed to find a way to keep the content but drop the related infrastructure, or be ready to definitively remove it.
Photo by Drew Beamer on Unsplash
Coming soon
This article presents the issues of the Bonita Documentation site 2016 version and why we needed to provide a refreshed site. In it, I have outlined both the issues and our “need to have” and “want to have” requirements to select a new solution for improvements.
In the next article, we’ll explain the actual technical choices we made for the new online documentation, and what we learned about our new technical stack from the migration. (Hint: we’re still here, and so is the Bonita documentation!)
Top comments (0)