Introducing Jargon — Creating your first Domain

5 min readJun 22, 2021

The problem with blank-pages

There’s nothing worse then starting new for the first time and being presented with a blank-page and no information on what to do.

We’re particularly conscious that this problem exists in Jargon, and have put in place some features to make your first steps a little easier.

The most obvious feature is: Each time that you create a new Domain, Jargon will offer to fill it with an example, so you can get away from that dreaded blank-page problem.

This article will take a look at that process, and talk a little about what a Domain is, and the important parts that you will want to know about before creating Domains of your own.

Creating a free account

If you haven’t done so already, you might want to sign up for a Jargon account — it’s completely free.

There’s a section in our Getting Started guide that covers Setting up your account. It only takes a couple of minutes and then you’ll be ready to follow along and create your own Domain.

You will need to verify your email address, but after that you’ll be able to create as many public Domains as you like.

What exactly is a Domain?

Jargon is inspired by a popular Software Engineering approach to breaking down complexity, called Domain-Driven-Design, and shares many of the same concepts.

Under Domain-Driven-Design, a Domain is;

A sphere of knowledge or activity, representing the business problem you are building a solution for

Taking a common example, if you were building a solution for an e-commerce platform, you could break it down into several Domains:

Customer
Order
Shipping
Payment

Each of these is a contained sphere of activity, and stands alone from any of the other Domains.

In order to make your Domains reusable for others, you should break them down into their smallest subject area possible.

Creating a Domain

Once you’ve signed in, and verified your email address, you’ll see a screen that looks a little bit like this:

A mostly blank-page, but with a helpful button to create a new Domain

Clicking the ‘New domain’ button will take you the new Domain page:

Let’s go through what each field here is for.

Domain Name: All Jargon Domains are identified by a combination of three parts, including the name of the Domain (also the name of the account that owns the Domain, and the Domain’s version number).

You will need to think pretty carefully about what you name your Domain, because you can’t change this afterwards.

Why can’t you change a Domain’s name?
A key part of Jargon is importing and reusing Domains, and their name is part of how they’re identified. If you could change a Domain’s name, you would break all of the Domains that import yours.

Domain names need only need to be unique within your account, so you have a lot of freedom to choose something that conveys meaning to other people.

Description: When people search for Domains, they’ll see this description in the results. Try to make it relevant to what your Domain is for, otherwise people might not investigate further.

You will have a chance to change this each time that you create a new release for your domain — more on that in future articles, or read our guide Releases and Importing.

This is a private Domain: Although a big part of Jargon is openly sharing Domains, there are times when you need to make one Private.

Please note that this will become a paid feature of Jargon in the future.

Once you’ve named and described your Domain go ahead and create it, and you’ll be taken to the Domain details page.

The Domain details page

There’s a lot to talk about on this page, but that will all have to wait for future articles.

This article is going to skip over all of the functionality this page has to offer, but I promise that there will be articles that cover off everything you need to know.

For now, the yellow highlighted box in the upper right corner is all you need to worry about — it’s how you access the editor for your domain.

Clicking the ‘Open the bleeding-edge version’ link will take you to the Domain Editor

The Domain Editor

Because this is a new Domain, Jargon offers to fill it with an example so you can quickly get started with something. Lets take a look at what that example gives us.

A Typical Jargon Domain

The Jargon Editor — where you create data models

The example is based on the Swagger Petstore, another illustrative example from the creators of Swagger and the OpenAPI specification.

The Editor is separated into 3 major columns. From left-to-right:

The text editor, which is where you actually create and model the domain
The diagram view, where you position and layout the domain
The properties pane, where you enrich the domain with things like data-definitions, filters and more (which will be the topic of future articles)

The example Domain is quite small and easy to understand. If you knew nothing else about Jargon, then just reading this example and playing around a little bit will give you most of the tools you need to create your own Domains.

Saving changes, and creating a snapshot

After you’ve played around for a bit, you will want to save your changes.

Clicking the save icon in the upper-right corner will bring up the save screen:

Here you have the option of saving your domain as a Snapshot — a named point in time view of the state of the Domain, or not. I highly recommend getting into the habit of saving regular snapshots, each time that you make an atomic change. That way, you will have a record of all the important changes you’ve made to a Domain when it’s time to create release notes.

Wrapping up

That’s enough for this article. If there is anything else you really need to know before the next article comes out, you can:

check the Getting Started Guide
leave a comment below
raise an issue at the jargon issue tracker GitHub repository