I implemented and lead the migration of the ICE Health Systems knowledge base from a Confluence and Scroll Viewport setup to one built on plain text Markdown files and the Docusaurus static site generator.
Impact#
I had a number of goals in starting this project:
- Shorten page loading times.
- Improve learner reading, navigation, and search experience.
- Integrate closer with the development team through a docs-as-code approach.
- Version control documentation with more precise details and fallbacks.
- Collect page analytics in a lightweight, privacy-friendly manner.
- Provide faster search and search term analytics.
After researching a number of alternatives, a Docusaurus documentation site built on git-controlled plain text files, hosted on Netlify with Plausible Analytics and Algolia Search integrations gave the team all the tools and more to achieve our goals.
Migrating the Confluence page content was a somewhat manual process, but HTML to Markdown conversion tools did most of the heavy lifting for version 01.
Refining important sections while still working on net new content was easy with git versioning and branching. We suddenly had a much more flexible workflow for running parallel projects to keep up with the Agile release cycle and still continuously refine existing materials.
Design Highlights#
The page loading speed of Docusaurus combined with Netlify’s CDN provided unbelievably fast loading times for learners. When I first explored the staging site I kept checking to see if something was wrong, because I couldn’t believe pages would load so quickly.
The improved portability of Markdown files as the basis of the documentation also enabled easier spinoff sites and PDF generation for custom client requests. I easily spun up and re-branded a handful of streamlined project documentation sites for white glove clients who were using the system for special projects.
As the site grew to include video pages as well, the fast navigation made it effortless for learners to navigate to related articles after watching a video, and provided a streamlined, branded experience within one site.
Credits#
I lead the project research, testing, and launch, with page migration support from the implementation department and domain management support from the cloud services team. All of the release notes, videos, and documentation were either newly created or substantially re-written by me during the migration.