2 minute read

Once you’ve created your Domain in Jargon, you will want some way to document it for others to discover and understand — that’s were a Readme comes in.

A readme is a page that Jargon hosts for you that you can customise to explain the ins and outs of your Domain to others.

Jargon can generate Readme content from data in your Domains

It’s written in Markdown, and comes with quite a handy library of content that you can include at the click of a button.

Let’s take a look at how to create one.

Making a Readme

A Readme is an artefact of a Domain, meaning it will be versioned and released alongside that Domain. To create one, head over to the artefacts tab, and click ‘Create a Readme’

captionless image

This will take you to the Readme editor. The library is on the left, and the content of the Readme is on the right:

The left hand pane lists the components that can be added, and the right hand pane is the content.

The Library

Jargon will scan you domain for interesting bits that you might want to add to your Readme, and lists them on the left hand side in the Library.

In the above example, the Domain we’re creating a Readme for (jargon/Cafe) has a selection of interesting things. From the top, they are:

  • A state lifecycle diagram
  • Data Model
  • API Specification
  • Definitions Table
  • Code Tables

This Domain also has an import, and the interesting parts of that import are also shown in the Library:

  • Data Model
  • Definitions Table

Clicking on anything in the Library will insert a block of Markdown into the Readme, which you can customise to suit your needs. Here’s an example:

Jargon creates blocks of Markdown to represent the different types of items you may want to add to your Readme

Here, I’ve clicked on the ‘Definitions Table’ button under jargon.Cafe. It’s inserted some header and link information, followed by a directive that Jargon interprets to generate the definitions table. This directive takes an array of Class names that you want included in the table, letting you tweak which classes are generated.

You can preview what the Readme will look like, using the buttons above the markdown (specifically, the eye icon here).

The generated definitions table

By using directives like this, your Readme doesn’t actually contain any of the definitions of the classes, and Jargon inserts the latest versions of them whenever your Readme is saved. This keeps your Domain models as the source of truth, and the Readme just organises that information to tell the story you want.

This approach is used for all Library items, so your readme will always stay up-to-date with the content in your Domian. It works for all Domain items, such as this state lifecycle diagram:

A reference to a stat life cycle diagram has been inserted into the Readme

Taking a look at the final Readme shows quite a comprehensive suite of documentation, and all it took was a couple of clicks.

Wrapping up

Creating a Readme is a great way to bring all your design work together into a single artefact that can be shared with teams wanting to learn more about how your Domains work.

Making information like this visible, and in a traceable and connected way, is a key concept in Jargon. Following these approaches greatly helps data discovery and interoperability.

If there is anything else you really need to know before the next article comes out, you can:

You May Also Enjoy