A Markdown/HTML + Diagram generator for Sysl specifications.

Objective#

The objective of sysl-catalog is to create the most seamless experience for engineers to document their API behaviour, as well as creating a standardised way multiple teams can create documentation whilst gaining mutual benefit from already existing documentation.

Background#

Let’s say that a team wants some diagrams to represent how their services interact with other services. First, the team needs to choose what format to use, then the team needs to decide on where the docs are going to be hosted, and how often they should be updated.

We, some of the ANZ open source engineers, have recently set up what we consider to be good engineering practises for our enterprise-backed open source project Sysl.

Often we have heard that software products were started when somebody scratched their own itch. And so it was with Marcelo and Sysl. Here's his story...

Sysl was born as a reaction to the state of architecture as I saw it when I joined ANZ (Australia and New Zealand Banking Group Limited): a morass of documents, spreadsheets and Visio diagrams depicting different parts of the architecture elephant with wildly different representations across platforms and no unified formalism to allow the architecture of the system to be understood and analysed as a whole. Moreover, once complete such designs fossilised rapidly, since there was no formal tie-in between them and the code that was derived from them. Generating code from these designs was an entirely manual process. As a coder by trade (and passion), I saw that none of the extant GUI-focused tooling was doing anything to remedy this, and I even suspected that they were part of the problem, so I decided to experiment with a text-based formalism to describe a system I was designing at the time.

Sysl (pronounced "sizzle") is a system specification language. Using Sysl, you can specify systems, endpoints, endpoint behaviour, data models and data transformations. The Sysl compiler automatically generates sequence diagrams, integrations, and other views. It also offers a range of code generation options, all from one common Sysl specification.