Skip to content

17: Adopt Zensical as Documentation Platform

Status

Status: Accepted

Context

We are currently using different documentation platforms:

  • MkDocs for opsdev.nz (production)
  • Hugo for startmeup.nz (regret this choice)

Hugo is Go-based and doesn't align with our Python-first infrastructure strategy. We are building packages for PyPI publication and want to create command line tools:

  • specmaint-opsdevnz
  • sprintmaint-opsdevnz
  • worklog-opsdevnz

Our infrastructure should be Python-first with RUST as secondary priority. But we are only saying that now since finding Zensical. But also looking at "uv" and the work astral.sh is doing that inspires us.

Over the past few years we have worked with Sphinx, Docusaurs and looked at hosted solutions like Gitbook and Notion that do not quite suite our needs. Sphinx is a strong contender though, but we are leaning more torward new and shiny rather than old and reliable. Docusaurus may in fact be best of breed, but we are not React fanboys.

Some other alternatives mentioned here:

Decision

We will adopt Zensical as our documentation platform successor to both MkDocs and Hugo. Zensical is RUST-based but available via PyPI, fitting well into our Python ecosystem while leveraging RUST performance benefits.

Rationalel

  1. Python Ecosystem Integration: Zensical is available via PyPI, allowing seamless integration with our Python-first infrastructure
  2. Consolidation: Replaces both MkDocs and Hugo, simplifying our documentation stack
  3. Performance: RUST-based backend provides better performance than Go-based Hugo
  4. Tool Development: Supports our goal of creating Python CLI tools like specmaint-opsdevnz
  5. Future-proof: RUST as secondary priority aligns with our infrastructure strategy

Consequences

Positive

  • Unified documentation platform across all projects
  • Better integration with Python tooling and PyPI packages
  • Improved performance with RUST backend
  • Simplified maintenance and deployment
  • Future service revenue opportunities through Zensical expertise

Negative

  • Migration effort from existing MkDocs and Hugo setups
  • New project not quite proven yet

Neutral

  • Requires updating CI/CD pipelines
  • May need custom integrations for existing workflows

Implementation Plan

  1. Evaluate Zensical features against current requirements
  2. Set up test instance for migration validation
  3. Migrate opsdev.nz from MkDocs to Zensical
  4. Migrate startmeup.nz from Hugo to Zensical
  5. Develop specmaint-opsdevnz CLI tool with Zensical integration
  6. Update documentation and deployment processes

Future Service Strategy

  • Plans to support Zensical-based sites as a future service offering
  • Intent to help clients migrate from other platforms (like mkdocs) to git-based documentation workflows
  • Description of Zensical Spark program and intention to join when service revenue makes it sensible
  • Recognition that the Spark program provides direct access to Zensical team and influence in design process
  • Develop service delivery capabilities for future client offerings